Welcome to BCIM’s documentation!¶

Intstalling Julia¶

The nightly build is recommended as development on BCIM is done on the developmental release branch. Nightlies can be found on the Julia download page. Better yet, build julia from source using the directions on the Julia github.

Python¶

Post processing is done in python 3.6, though any release of python 3 should work. Follow a guide online on how to install python 3 for your environment.

Matplotlib and Numpy¶

BCIM uses Matplotlib for graphics and Numpy for numerical work. Both can be installed using pip:

pip install numpy matplotlib

BCIM¶

BCIM can be installed by cloning into the git repository on github:

git clone https://github.com/dankolbman/BCIM
cd BCIM

The src directory will have to be added to your shell path or the src/julia/BCIM.jl module can be inculeded by absolute reference inside your run files.

Running¶

To run a simulation like the example below, Julia must be invoked from the top level directory of the repository (where the src folder resides), a from a directory that is appropriate for the include statement to find the source files. The simulation can then be run by passing the script to Julia:

julia examples/num_part.jl

Running on a Cluster¶

Using slurm, many identical simulations can be run at once. The following will run the adh.jl script on 10 different cores with 2048Mb allocated on each.

srun -N 10 -t 2000 –mem-per-cpu=2048 julia runs/vary_params/adh.jl

Quick Example¶

The following can be found in examples/num_parts.jl in the source. It creates an experiment with three trials and runs each one. It then modifies the parameters and creates a new experiment with a different number of particles. It repeats this three times for three different experiments each with three identical trials.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

## Runs a experiments for diffrent numbers of particles
# Each experiment consists of three trials
# Saves data to data/numparts/ relative to run path

include("../src/julia/BCIM.jl")
#using BCIM

# Hack to allow asynchronous experiment runs
sleep(rand()*10)

# Our physical constants
pc = BCIM.PhysicalConst(  1.0e-5,           # dt
                          # Packing fraction
                          0.60,
                          # Eta
                          0.01,
                          # Temperature (K)
                          298.0,
                          # Boltzmann constant
                          1.38e-16,
                          # Propulsisions [ sp1, sp2 ]
                          [0.0,1.0e3],
                          # Repulsions [ sp1, sp2 ]
                          [1.5e4,1.5e3],
                          # Adhesions [ sp1, sp2, sp1-sp2 ]
                          [1.5e3, 0.0, 0.0 ],
                          # Cell division time ( 0 = no division)
                          [ 0.01, 0.01 ],
                          # Efective adhesive contact distance
                          0.1,
                          # Cell diameter
                          15.0e-4,
                          # Number of particles [ sp1, sp2 ]
                          [256,256])

##### 256 particles total
pc.npart = [128, 128]
# Initialize experiment with 3 trials in given directory with desired constants
exp = BCIM.Experiment("data/ex/256", 3, pc, false)

# Run the experiment
# Equilibriate for 1000 steps
# Collect every 1000 steps
# Run for 100000 steps
BCIM.run(exp, 1000:1000:100000)

##### Run again for 512 particles total
pc.npart = [256, 256]
exp = BCIM.Experiment("data/ex/512", 3, pc, false)
BCIM.run(exp, 1000:1000:100000)

##### 1024 particles total
pc.npart = [512, 512]
exp = BCIM.Experiment("data/ex/1024", 3, pc, false)
BCIM.run(exp, 1000:1000:100000)

Experiment¶

The experiment type is used to handle several trials of a simulation. It is responsible for creating paths for the trial simulations and saving parameters for them.

Simulation¶

The simulation type is used to contstruct a simulation system and run it for a desired amount of steps. It is responsible for steping the system and performing scheduled analysis of the system state, including writing the state to disk and calculating statistical quantities for the system.

Physical Constants¶

The PhysicalConst type has many fields describing the physical (dimensional) parameters of the system:

PhysicalConst(dt, phi, eta, temp, boltz, prop, rep, adh, contact, dia, npart, diff, rotdiff)¶

Parameters:

dt – the time constant phi – the packing fration eta – the viscosity temp – the system temperature boltz – boltzmann’s constant prop – the propulsion for each species rep – the repulsion for each species adh – the adhesion for each species contact – the contact distance as a fraction of the diameter dia – the diameter of each particle npart – the number of particles of each species diff – the diffusion rotdiff – the rotational diffusion

Dimensionless Constants¶

The DimensionlessConst type has many fields corresponding to dimensionless parameters of the system. A dimensionless type can be invoked by passing it a PhysicalConst type from which it will produce dimensionless parameters by scaling appropriatly.

DimensionlessConst(dt, phi, eta, temp, boltz, prop, rep, adh, contact, dia, npart, diff, rotdiff, pretrad, prerotd)¶

Parameters:

dt – the time constant phi – the packing fration eta – the viscosity temp – the system temperature boltz – boltzmann’s constant prop – the propulsion for each species rep – the repulsion for each species adh – the adhesion for each species contact – the contact distance as a fraction of the diameter dia – the diameter of each particle npart – the number of particles of each species diff – the diffusion rotdiff – the rotational diffusion pretrad – the prefactor for translational diffusion prerotd – the prefactor for rotational diffusion

System¶

The System type is used to represent a physical system. It holds a list of particles which it is simulating, the dimensionless parameters of the system, and a CellGrid which is used to efficiently sort and simulate the particles.

System(dc)¶

Parameters:	dc – the dimensionless contstants for the system

Initializes a system using the dimensionless parameters dc. Constructs a cell grid and particles based on the specification of the parameters.

uniformSphere(dc)¶

Parameters:	dc – the dimensionless contstants for the system

Creates a list of particles, the number of which are specified by the npart field of dc, that have been randomly distributed in a sphere.

step(s)¶

Parameters:	s – the system to make a step on

Steps a system s by one step by calling the force calculation function.

assignParts(s)¶

Parameters:	s – the system to assign particles in

Assigns particles in a system into Cells in the system’s CellGrid. Called by Simulation during a run periodically so collision checks can be made efficiently using the cell grid.

Part¶

The Part type is used to represent a particle in the system.

Part(id, sp, pos, vel, ang)¶

Parameters:	id – the particle id sp – the particle species pos – the position vector of the particle vel – the velocity vector of the particle ang – the angle vector of the particle

Log¶

Log(path, verbose=false)¶

Parameters:	path – the file to output logs to verbose – whether or not to pipe log to STDIN in addition to the file

log(l, output)

Parameters:	l – the log instance being logged to output – the output string to write