ReaDDy - A particle-based
reaction-diffusion simulator

Practical sessions

Here we’ll gather the material and tasks for the daily sessions.

Monday - ReaDDy intro

Task 1) installation

Get miniconda and install it

wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

If your home directory is limited in space, you might want to install it under storage, i.e. when prompted for install location, choose either /home/mi/user/miniconda3 or /storage/mi/user/miniconda3 (replace user with your username). Your ~/.bashrc should contain the line

. /storage/mi/user/miniconda3/etc/profile.d/conda.sh

to enable the conda command. If you try out which conda, you should see its function definition, and you’re good to go.

Create a conda environment workshop

conda create -n workshop

and activate it.

conda activate workshop

Add conda-forge as default channel

conda config --add channels conda-forge --env

and install the latest readdy in it

(workshop) $ conda install -c readdy readdy

Check if it worked, start a python interpreter and do

import readdy
print(readdy.__version__)

If this does not return an error, you are ready to readdy (almost). Make sure you also have vmd installed. It should be installed on the universities machines.

Tuesday

Wednesday

Thursday

Friday

Cookbook

This section has some solutions to common problems you might run into.

  • The order in which you create and manipulate the system and simulation matters!

Remember that the workflow should always be

system = readdy.ReactionDiffusionSystem(...)
# ... system configuration
simulation = system.simulation(...)
# ... simulation setup
simulation.run(...)
# ... analysis of results

If you made a mistake while registering species, potentials, etc., just create a new system and run the configuration again. The same goes for the simulation, just create a new one. In the jupyter notebooks it is sufficient, to just run all the cells again.

  • Simulation box and box potential for confining particles

If you want to confine particles to some cube without periodic boundaries, the box potential must be fully inside the simulation box. Remember that the box is centered around (0,0,0). For example the following will confine A particles to a cube of edge length 10

system = readdy.ReactionDiffusionSystem(
    box_size=[12., 12., 12.], unit_system=None,
    periodic_boundary_conditions=[False, False, False])
system.add_species("A", 1.)
origin = np.array([-5., -5., -5.])
extent = np.array([10., 10., 10.])
system.potentials.add_box(
    "A", force_constant=10.,
    origin=origin, extent=extent)

The two vectors origin and extent span a cube in 3D space, the picture you should have in mind is the following

  • Initial placement of particles inside a certain volume

If you have already defined origin and extent of your confining box potential, it is easy to generate random positions uniformly in this volume

n_particles = 30
uniform = np.random.uniform(size=(n_particles,3))
init_pos = uniform * extent + origin

Here uniform is a matrix Nx3 where each row is a vector in the unit cube $\in{[0,1]\times[0,1]\times[0,1]}$ . This is multiplied with extent, yielding a uniform cube ${[0,\mathrm{extent}_0]\times[0,\mathrm{extent}_1]\times[0,\mathrm{extent}_2]}$. If you add the origin to this you get this cube at the right position (with respect to our box coordinates centered around (0,0,0)), i.e.

  • 2D plane

If you want to confine particles to a 2D plane, just use the box potential but make the extent in one dimension very small, i.e.

system = readdy.ReactionDiffusionSystem(
    box_size=[12., 12., 3.], unit_system=None,
    periodic_boundary_conditions=[False, False, False])
system.add_species("A", 1.)
origin = np.array([-5., -5., -0.01])
extent = np.array([10., 10., 0.02])
system.potentials.add_box(
    "A", force_constant=10.,
    origin=origin, extent=extent)

Having defined origin and extent it is now easy to add particles to this 2D plane. Note that I also made the box_size in z direction smaller, however it should be large enough.

  • Output file size

Please make use of your /storage/mi/user directories, your home will fill up quicker.

data_dir = "/storage/mi/user" # replace user with your username
simulation.output_file = os.path.join(data_dir, "myfile.h5")

Additionally, use a stride on your observables, e.g.

simulation.record_trajectory(stride=100)
# or
simulation.observe.particle_positions(stride=100)
  • Reaction descriptor language

In expressions like

system.reactions.add("fus: A +(2) B-> C", rate=0.1)

the value in the parentheses +(2) is the reaction distance.

  • look at VMD output if something is fishy

This might reveal some obvious mistakes. Therefore you must have registered the according observable

simulation.record_trajectory(stride=100) # use appropriate stride
# ... run simulation
traj = readdy.Trajectory(simulation.output_file)
traj.convert_to_xyz(particle_radii={"A": 0.5, "B": 1.})
# particle_radii is optional here

Then in a bash shell do

vmd -e myfile.h5.xyz.tcl

or prefix with ! in the jupyter notebook.

© Copyright 2019 CMB group