Input files

The system file is a simple text file that defines all parameters of the simulation. The MEDYAN executable must take in a system file as a command line argument. The parameters are defined in a s-expressions:

(parameter          parameter-value)
(parameter-group
    (property-1     property-1-value)
    (property-2     property-2-value))

The input files can also be generated using MEDYAN's interactive configuration by running medyan config, which provides limited configuration capabilities.

All physical quantities in the input files will use the following base units, unless otherwise specified.

name unit
time s
length nm
mass g

Some common derived units are displayed below.

name unit
force pN
energy pN⋅nm
diffusion coefficient nm²/s

System input files

Geometry

The following geometric parameters can be set. All geometry parameters must be set in the system file, or a startup error will result.

item type description
NX int Number of compartments in X direction.
NY int Number of compartments in Y direction.
NZ int Number of compartments in Z direction.
COMPARTMENTSIZEX double Size of compartment in X direction.
COMPARTMENTSIZEY double Size of compartment in Y direction.
COMPARTMENTSIZEZ double Size of compartment in Z direction.
MONOMERSIZE double Size of monomer for filament growth .
CYLINDERSIZE double Size of cylinder in filament.
BOUNDARYSHAPE {SPHERICAL, CUBIC, CAPSULE} Boundary shape.
BOUNDARYDIAMETER double Diameter for applicable shapes, including SPHERICAL and CAPSULE geometries.

If movement of boundaries is desired, the following parameters can also be set. If these parameters are not set, the system will assume non-moving boundaries. Currently, moving boundaries are only implemented for the CUBIC boundary shape.

item type description
BOUNDARYMOVE {NONE, ALL, TOP} Movement of a boundary. ALL specifies that all boundaries will move in the given direction, and top specifies that the top of the boundary in the z direction will move.
BMOVESPEED double Speed of boundary movement in nm/s. If a negative value is given, the boundary will move towards the center of the grid. If positive, the boundary will move away from the center of the grid.
BMOVESTARTTIME double Time at which the boundary will begin to move. If not specified, the boundary will start moving at the beginning of the simulation.
BMOVEENDTIME double Time at which the boundary will stop movement.

Mechanics

The following mechanical parameters can be set. It is noted that the number of parameters for each force field must match the number of species of that type, specified in the system input file. This must be consistent for all simulation elements, including filaments, cross-linkers, motors, branchers, and bubbles. To set multiple parameters corresponding to multiple species, list the parameter values with space in between after the parameter qualifier. If a force field type is left blank, that force field will not be included in the simulation.

item type description
FSTRETCHINGTYPE {HARMONIC} Filament stretching force field.
FSTRETCHINGK double Filament stretching force constant.
FBENDINGTYPE {HARMONIC, COSINE} Filament bending force field.
FBENDINGK double Filament bending force constant.
FBENDINGTHETA double Filament bending angle (radians).
LSTRETCHINGTYPE {HARMONIC} Cross-linker stretching force field.
LSTRETCHINGK double Cross-linker stretching force constant.
MSTRETCHINGTYPE {HARMONIC} Motor stretching force field.
MSTRETCHINGK double Motor stretching force constant.
BRSTRETCHINGTYPE {HARMONIC} Branching point stretching force field.
BRSTRETCHINGK double Branching point stretching force constant.
BRBENDINGTYPE {COSINE} Branching point bending force field.
BRBENDINGK double Branching point bending force constant.
BRBENDINGTHETA double Branching point bending angle (radians).
BRDIHEDRALFFTYPE {COSINE} Branching point dihedral force field.
BRDIHEDRALK double Branching point stretching force constant.
BRPOSITIONTYPE {HARMONIC} Branching point position force field.
BRPOSITIONK double Branching point position force constant.
VOLUMEFFTYPE {REPULSION} Volume force type.
VOLUMECUTOFF double Volume interaction cutoff distance.
VOLUMEK double Volume force constant.
BOUNDARYFFTYPE {REPULSIONEXP} Boundary force type.
BOUNDARYCUTOFF double Boundary interaction cutoff distance.
BOUNDARYINTERACTIONK double Boundary force constant.
BOUNDARYSCREENLENGTH double Boundary screening length constant.
BUBBLEFFTYPE {REPULSIONEXP} Bubble force type.
BUBBLECUTOFF double Boundary interaction cutoff distance.
BUBBLEINTERACTIONK double Bubble force constant.
BUBBLESCREENLENGTH double Bubble screening length constant.
BUBBLERADIUS double Bubble radius.
NUMBUBBLETYPES int Number of different bubble types.
MTOCFFTYPE {ATTACHMENTHARMONIC} MTOC force type.
membrane-tension-ff-type {CONSTANT} Membrane tension type.
membrane-bending-ff-type {HELFRICH, HELFRICH_QUADRATIC} Membrane bending type. In quadratic mode, the spontaneous curvature is always assumed to be zero.
volume-conservation-ff-type {MEMBRANE} Volume conservation type.
triangle-bead-volume-ff-type {REPULSION} Triangle bead volume exclusion force type.
triangle-bead-volume-k float Triangle bead volume exclusion force constant.
triangle-bead-volume-cutoff float Triangle bead volume exclusion cutoff distance.
triangle-bead-volume-cutoff-mech float Triangle bead volume exclusion cutoff distance during mechanical minimization.

The system mechanical energy is minimized using the minimization algorithm, whose parameters can be specified as follows.

item type description
CONJUGATEGRADIENT {POLAKRIBIERE, FLETCHERRIEVES, STEEPESTDESCENT} Type of conjugate gradient minimization.
GRADIENTTOLERANCE double Gradient tolerance in conjugate gradient (in pN).
MAXDISTANCE double Maximum distance beads can be moved in minimization.
LAMBDAMAX double Maximum lambda that can be returned in line search.
try-to-recover-in-line-search-error {false, true} Defaults to true. If set to false, whenever line search fails to find a lower energy, the program will terminate with a diagnostic message.

Chemistry

The following chemical parameters can be set. It should be noted that the number of parameters listed for each chemical species type that resides on a filament must match the number of filament types, specified in the system input file. This must be consistent for all filament types. To set multiple parameters corresponding to multiple filaments, list the parameters with space in between after the parameter qualifier.

All chemical parameters must be set unless otherwise noted in the description. For the motor parameters, the number of parameters must match the number of motor species in the system. For more information on chemical algorithms, see Popov et al (2016).

An alternate set of parameters can be specified in replacement of RUNTIME for smaller systems in which simulation time is based on explicit reaction steps; if RUNTIME is not initialized or set to zero, the parameter RUNSTEPS and its associated chemical step-based parameter set will be used if provided.

item type description
CHEMISTRYFILE string Input chemistry file. Should be in the input directory.
CALGORITHM {GILLESPIE, NRM} Chemistry algorithm used.
RUNSTEPS int Number of total chemical steps. If RUNTIME is set, will not be used.
RUNTIME double Total runtime of simulation.
SNAPSHOTSTEPS int Number of steps per snapshot. If SNAPSHOTTIME is set, will not be used.
SNAPSHOTTIME double Time of each snapshot.
MINIMIZATIONSTEPS int Number of chemical steps per mechanical equilibration. If MINIMIZATIONTIME is set, will not be used.
MINIMIZATIONTIME double Time between each mechanical equilibration.
NEIGHBORLISTSTEPS int Number of chemical steps per neighbor list update. This includes updating chemical reactions as well as force fields which rely on neighbor lists. If NEIGHBORLISTTIME is set, will not be used.
NEIGHBORLISTTIME double Time between each neighbor list update.
INITIALSLOWDOWNTIME double Length of time at the beginning of the simulation to run mechanical equilibrations and neighbor list updates 10x more frequently. Disabled by default.
NUMFILAMENTTYPES int Number of different filament types.
NUMBINDINGSITES int Number of binding sites per cylinder for each filament type defined. This will set binding sites for cross-linkers, motors, and other binding molecules.
NUMMOTORHEADSMIN int Minimum number of motor heads per motor species defined.
NUMMOTORHEADSMAX int Maximum number of motor heads per motor species defined.
MOTORSTEPSIZE double Single motor head step size.
DISSIPATIONTRACKING {OFF, ON} Whether to switch on the dissipation tracking feature.
LINKERBINDINGSKIP int Switches on the different binding tracking feature to allow motors to have more binding spots per cylinder than linkers. The specified integer is the number of binding sites that the cross-linkers will skip before accepting a possible binding site.
allow-same-filament-pair-binding bool Whether pairwise bindings on the same filament is allowed. Even if this is turned off, pairwise bindings will not happen on same or neighboring cylinders.
EVENTTRACKING {OFF, ON} Whether to switch on the event tracking feature.

Dynamic rates

The following dynamic rate forms and parameters can be set. These parameters are characteristic lengths and amplitudes of the rate changing equations outlined in Popov et al (2016). These can be tuned to mimic the stall and unbinding mechanochemical coupling of cross-linkers and myosin II motors. Note that if dynamic rates are enabled, the number of dynamic rate forms for each type of reaction must match the number of species of that type specified in the system input file, i.e. the number of forms for cross-linker unbinding must match the number of cross-linker species, etc.

The number of parameters specified for each type of dynamic rate form must match the number of parameters required for those forms. See below for details, and see Popov et al (2016) for more information on the explicit forms. Parameters must be listed in order of the form that they correspond to, also corresponding to the species that they represent.

item type description
DFPOLYMERIZATIONTYPE {BROWRATCHET} Filament polymerization dynamic rate form.
DFPOLYMERIZATIONLEN double Characteristic length for filament polymerization dynamic rate form.
DLUNBINDINGTYPE {CATCHSLIP, SLIP} Cross-linker unbinding dynamic rate form. If CATCHSLIP, two parameters for DLUNBINDINGLEN and DLUNBINDINGAMP are needed to define the functional form. If SLIP, one DLUNBIDINGLEN is needed to define the functional form.
DLUNBINDINGLEN double Characteristic length of cross-linker unbinding dynamic rate form.
DLUNBINDINGAMP double Amplitude of cross-linker unbinding dynamic rate form.
DMUNBINDINGTYPE {LOWDUTYCATCHSLIP, LOWDUTYSLIP} Myosin II unbinding dynamic rate form. If LOWDUTYCATCHSLIP, two parameters for DMUNBINDINGFORCE are needed to define the functional form. If LOWDUTYSLIP, one DMUNBIDINGFORCE is needed to define the functional form.
DMUNBINDINGFORCE double Characteristic force of myosin II unbinding dynamic rate form.
DMWALKINGTYPE {LOWDUTYSTALL} Myosin II walking dynamic rate form.

Membrane profile and initialization

A membrane profile can be defined using the following syntax:

(membrane <profile-name>
    (<property> <value>)
    ...)

where membrane properties include the following parameters.

item type description
vertex-system {material, general} In material vertex system, each vertex represents a patch of membrane with a fixed number of lipid molecules. In general vertex system, a vertex simply represents a point on the membrane surface.
area-k float Area elasticity of membrane. Unit pN/nm.
bending-k float Bending elasticity of membrane. Unit pN⋅nm.
eq-curv float Spontaneous curvature of membrane. Unit 1/nm.
tension float Membrane tension. Unit pN/nm.
volume-k float Volume conservation force constant of a enclosing membrane. Unit pN/nm².

Membrane can be initialized with a specified membrane profile, using the following properties:

(init-membrane <profile-name>
    (<property> <value>)
    ...)

If the membrane profile name was not defined in the input file, a startup error will occur. The membrane initialization properties are defined using the following parameters.

Starting filament configuration

These parameters define the initial configuration and length of filaments in the system. It is noted that at least one filament, plus end, and minus end chemical species must be initialized in the chemistry input file, or a startup error will result.

item type description
FILAMENTFILE string Name of filament initialization file. This is not required.
NUMFILAMENTS int Number of random filaments to initialize. These filaments will be randomly distributed in the system volume.
FILAMENTLENGTH int Number of cylinders per filament to initialize, defining the initial length of the filaments.
FILAMENTTYTPE int Filament type to initialize.
PROJECTIONTYPE {STRAIGHT, ZIGZAG, ARC, PREDEFINED} Specifies how the beads are sampled between two ends of a filament.

Projection type meaning for a filament specified by a set of 3D Cartesian coordinates [v0, v1, v2 ...], and the number of beads.

Starting bubble configuration

The following bubble initialization parameters can be set. These parameters define the initial configuration of bubbles in the system, similar to the filament configuration parameters. It is noted that at least one type of bubble must be set, or a startup error will result.

item type description
BUBBLEFILE string Name of bubble initialization file. This is not required.
NUMBUBBLES int Number of random filaments to initialize. These filaments will be randomly distributed in the system volume.
BUBBLETYTPE int Bubble type to initialize.

Special setup

The following special setups can be initialized with corresponding parameters. These setups must be set on different lines, so users should specify a new parameter, on separate lines, for each setup desired:

item type description
SPECIALSETUP MTOC Type of special setup.

For a microtubule organizing center (MTOC) setup, the following parameters can be defined:

item type description
MTOCFILAMENTTYPE int Type of filament to attach to the MTOC.
MTOCNUMFILAMENTS int Number of filaments to create and attach to the MTOC.
MTOCFILAMENTLENGTH int Length of filaments to attach to the MTOC, in number of cylinders.
MTOCBUBBLETYPE int Type of bubble to be the MTOC.

Special protocols

The following special protocols can be initialized. These protocols must be set on different lines, so users should specify a new parameter, on separate lines, for each setup desired:

item type description
SPECIALPROTOCOL {MAKEFILAMENTSSTATIC, MAKELINKERSSTATIC} Make either filament or cross-linker chemistry static after a certain amount of time. This parameter must be followed by a double specifying the simulation time that this protocol is activated.
SPECIALPROTOCOL TRANSFERSHAREAXIS char X OR Y OR Z the axis along which compartments should be activated/deactivated based on the span of actin network. Currently implemented only for cubic boundary framework.
SPECIALPROTOCOL PINBOUNDARYFILAMENTS <pinK> <pinDistance> <pinTime> to tether minus and plus ends that are within pinDistance (nm) from the boundary after pinTime (s). This will result in additional forces on the actin network form the boundary.

Chemistry input files

The chemistry input file, whose name is specified in the system input file, contains the chemical configuration of the system, including species and reactions. It is noted that the order in which cross-linker, motor, and branches species are defined in the chemistry input file should match the relevant mechanical parameters, which are defined in the system input file. The number of species of each type should also match the SystemFile’s species type numbers, or a startup error will result. All species names given must be unique strings, or a startup error will result. In all species and reaction definitions, FILAMENTTYPE is an integer that specifies the type of filament that this filament species belongs to. For example, if there are two filament types defined, the FILAMENTTYPE parameter could be 0 or 1. An invalid value of this parameter will result in an error.

Species

Different types of species can be defined as follows:

Binding sites

For every species that binds to filaments (linkers, motors, branchers), a binding site species must be set. This binding site must be a bound species on any filament type. It is declared in the following form:

LINKERBINDINGSITE    <NAME> <FILAMENTTYPE>
MOTORBINDINGSITE     <NAME> <FILAMENTTYPE>
BRANCHERBINDINGSITE  <NAME> <FILAMENTTYPE>

where NAME is the name of a pre-defined bound species on a filament of type FILAMENTTYPE.

Reactions

Reaction definitions must follow these common rules:

Different types of reactions can be defined as follows: