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 (nm).
CYLINDERSIZE	double	Size of cylinder in filament (nm).
BOUNDARYSHAPE	{SPHERICAL, CUBIC, CAPSULE}	Boundary shape.
BOUNDARYDIAMETER	double	Diameter for applicable shapes, including SPHERICAL and CAPSULE geometries.

The CUBIC BOUNDARYSHAPE creates boundary planes 25nm in from the faces of compartment grid.

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	{integral, monomer}	Volume force type. When monomer-based volume exclusion is used, `volume-exclusion-monomer-interval` can be specified as well. `REPULSION` is the old option for `integral`, but its use is deprecated.
VOLUMECUTOFF	double	Volume interaction cutoff distance (nm). The volume force is only calculated on pairs of cylinders with mid points closer than this distance. This should always be larger than `CYLINDERSIZE`
VOLUMEK	double	Volume force constant.
volume-exclusion-monomer-interval	list int	Interval of monomer sampling for volume exclusion for each filament type.
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.

mesh: A list describing the initial membrane shape. Currently supporting the following shapes:
- An ellipsoid whose principal axes are parallel with the x, y, and z axes. Usage: ELLIPSOID center-x center-y center-z radius-x radius-y radius-z.
- A plane specified by a point and a normal vector. A bounding box is also needed to specify the sampling range. Usage: PLANE center_xyz... normal_xyz... box_origin_xyz... box_size_xyz....
eq-area-factor: A floating point value, such that the equilibrium area is the initial area multiplied by this factor.

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.

STRAIGHT - Creates a filament with minus end at v0, and extends number-of-bead full-size cylinders in v0 -> v1 direction. v2, v3 ... are ignored.
ZIGZAG - Creates a filament with minus end at v0, and extends number-of-bead full-size cylinders in (1) v0 -> v1 direction (2) another different direction alternatively. v2, v3 ... are ignored.
ARC - Not sure. (TODO: NEED DOCS)
PREDEFINED - Creates a filament with bead coordinates [v0, v1, v2 ...]. WARNING: Each cylinder in the filament is treated as a full-sized cylinder, no matter what the initial bead coordinates are. That means each cylinder in the filament can be compressed or stretched initially.

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.

The following syntax is used to initialize a Microtubule Organizing Center (MTOC), or a bead for Atomic Force Microscopy (AFM), which are both implemented as a bubble with extra parameters.

(init-mtoc
    (<property> <value>...)
    ...)
(init-afm
    (<property> <value>...)
    ...)

where most properties are shared by both MTOC and AFM. The properties are listed below.

item	type	description
bubble-type	int	Type of bubble to initialize.
bubble-coord	list float	Coordinates of the bubble center.
bubble-fixed	{false, true}	If the bubble is fixed, it's coordinates will not change during energy minimization.
filament-type	int	Type of filament attachment.
num-filaments	int	Number of filaments to attach to the bubble.
num-cylinders-per-filament	int	Number of cylinders per filament to attach to the bubble.
theta1, theta2, phi1, phi2	float	Restricts the initial orientation of the filaments under certain transformations (read source code to see the details). Default to (0, 1, 0, 1), which allows all possible orientations.
attachment-stretching-k	float	Stretching force constant for filament attachments.

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.

(SPECIALPROTOCOL <name> <parameters>...)

name	parameters	description
PINBOUNDARYFILAMENTS	`<pinK> <pinDistance> <pinTime>`	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.
PINLOWERBOUNDARYFILAMENTS	`<pinK> <pinTime> <pinFraction>`	Tether minus and plus ends that are within `pinDistance` (nm) from the lower boundary after `pinTime` (s). `pinDistance` has a default value (250 as of v5.1.0), but can be overwritten by other pinning protocols.
pin-initial-filament-below-z	`<pinK> <pinZ>`	Pin all initial beads with z coordinate lower than `pinZ` (nm).
MAKEFILAMENTSSTATIC, MAKELINKERSSTATIC	`<time>`	Make either filament or cross-linker chemistry static after a certain amount of `time`.
RATEDEPEND	`<time> <force>`	Starting at `time`, increase plus end polymerization rate for actin filaments under larger tension than `force` (pN).
AFM	`<step1> <step2> <iter-change> <step-total> <step-time>`	AFM protocol.
scale-membrane-eq-area	`<rate> <min-eq-area>`	For all membranes without lipid reservoir, increase its equilibrium area with `rate` (nm^2/s). Each equilibrium area cannot drop below `min-eq-area` (nm^2).
scale-membrane-eq-volume	`<rate> <min-eq-volume>`	For all closed membranes, increase its equilibrium volume with `rate` (nm^3/s). Each equilibrium volume cannot drop below `min-eq-volume` (nm^3).

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:

A diffusing species is defined in the following form:

⚠️ Breaking change starting MEDYAN v5.1.0, <DIFFCOEFF> means the 3D diffusion coefficient with dimension nm²/s. Previously, it meant the diffusion reaction rate between compartments with dimension s^-1, obtained from diffusion coefficient and the size of a cubic compartment. For example, if 500 nm compartments were used and the diffusion reaction rate was "1.0", it should be changed to "0.25E6".
```
SPECIESDIFFUSING <NAME> <COPYNUMBER> <DIFFCOEFF> <RELEASETIME> <REMOVALTIME> <QUALIFIER> (<NUMEVENTS>)
```
where NAME is any string defining the name of the species, COPYNUMBER is the number of molecules of that species in the system, and DIFFCOEFF is a float value that determines the diffusion coefficient of this molecule in the solution. RELEASETIME specifies when this molecule populates the system in simulation (in seconds). REMOVALTIME specifies whether the species should be removed from the simulation. If no removal is desired, this can be set to 0.

The QUALIFIER field is used to define the type of reacting species. The options are the following:
- REG : A regular reacting species. Copy numbers are updated typically.
- AVG : An averaging reacting species. The species will use a copy number averaged over a set number of copy number changes (NUMEVENTS) for efficiency.
The NUMEVENTS field, denoted in parentheses as optional, only used in the case of defining an averaging reacting species. If using a regular, this should not be included in the file or an error will result.
A bulk species, which is assumed to be spatially homogeneous, is defined in the following form:
```
SPECIESBULK <NAME> <COPYNUMBER> <RELEASETIME> <REMOVALTIME> <QUALIFIER>
```
where NAME is any string defining the name of the species, COPYNUMBER is the number of molecules of that species in the system, and RELEASETIME specifies when this molecule populates the system in simulation (in seconds). REMOVALTIME specifies whether the species should be removed from the simulation. If no removal is desired, this can be set to 0. The QUALIFIER field is used to define the type of reacting species. The options are the following:
- REG : A regular reacting species. Copy numbers are updated typically.
- CONST : An constant reacting species. The species will never change copy number upon reacting.
Any filament-related species can be defined in the following form:
```
SPECIES<SPECIESTYPE> <NAME> <FILAMENTTYPE>
```
where SPECIESTYPE can be:
- FILAMENT : A filamentous species. At least one filament species must be defined if using filaments in simulation.
- PLUSEND : A plus end species on a filament, which is defined as the front of the filament. There must be at least one plus end species for every filament species defined in the system.
- MINUSEND : A minus end species on a filament, which is defined as the back of the filament. There must be at least one minus end species for every filament species defined in the system.
- BOUND : A bound species on a filament. There must be at least one bound species defined for each filament type.
- LINKER : A cross-linker species. The ordering of cross-linker initializations should match their mechanical parameters, as stated above.
- MOTOR : A myosin II motor species. The ordering of motor initializations should match their mechanical parameters, as stated above.
- BRANCHER : A branching species. The ordering of branches initializations should match their mechanical parameters, as stated above.

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:

Species that are defined in reactions must be previously defined in the chemistry file.
For filament-related reactions, most species type and ordering parameters are fixed; if they are fixed, they will be pre-defined in the reaction definition below. If the ordering is not properly followed, a startup error will result.
All species declarations in a reaction must be separated by white space, with + markers between reactants and products. A -> must be placed between reactants and products, separated by whitespace. If this syntax is not followed, a startup error will result.
The optional string HRCDID and accompanying float DELGZERO specify the identity and the ∆G_0 value for the reaction, respectively, for use in dissipation tracking. If this feature is turned on, then this field must be supplied, and if it is turned off then this field must be omitted. Currently only some reactions support dissipation tracking, as specified below, and it is only supported when the Next Reaction Method algorithm choice is used. For those reactions which do not support dissipation tracking, the HRCDID and DELGZERO fields should not be set. This allows those reactions to be included in the chemical system while allowing dissipation tracking for supported reactions.

Different types of reactions can be defined as follows:

A general reaction between any bulk or diffusing species can be defined in the following form:
```
(GENREACTION
    [<DELGZERO>:<HRCDID>]
    <NAME>:BULK/DIFFUSING + <NAME>:BULK/DIFFUSING + ...
        -> <NAME>:BULK/DIFFUSING + <NAME>:BULK/DIFFUSING + ...
    <RATE>)
```
where any bulk or diffusing species can be included, and RATE is a float value that determines the rate constant of the reaction.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A bulk reaction between bulk species only can be defined in the following form:
```
BULKREACTION <NAME>:BULK + <NAME>:BULK + ... -> <NAME>:BULK + <NAME>:BULK + ... <RATE>
```
where any bulk species can be included. If the reaction only contains bulk species, it must be specified as a bulk reaction. RATE is a float value that determines the rate constant of the reaction.

This reaction does not support dissipation tracking, so HRCDID and DELGZERO should not be provided.
A polymerization reaction can be defined in the following form:
```
(POLYMERIZATIONREACTION
    [<DELGZERO>:<HRCDID>] <FILAMENTTYPE>
    <NAME>:BULK/DIFFUSING + <NAME>:PLUSEND/MINUSEND
        -> <NAME>:FILAMENT + <NAME>:PLUSEND/MINUSEND
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. It is noted that the first species listed can be either DIFFUSING or BULK, and the reaction can contain a PLUSEND or MINUSEND.

This reaction will polymerize the filament, producing a new chemical species on the end of the filament and increasing the length of the filament by a single monomer.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A depolymerization reaction can be defined in the following form:
```
(DEPOLYMERIZATIONREACTION
    [<DELGZERO>:<HRCDID>] <FILAMENTTYPE>
    <NAME>:FILAMENT + <NAME>:PLUSEND/MINUSEND
        -> <NAME>:BULK/DIFFUSING + <NAME>:PLUSEND/MINUSEND
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. It is noted that the third species listed can be either DIFFUSING or BULK, and the reaction can contain a PLUSEND or MINUSEND.

This reaction will depolymerize the filament, removing a chemical species from the end of the filament and decreasing the length of the filament by a single monomer.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A cross-linker reaction between two filaments can be defined in the following form:
```
(LINKERREACTION
    [<DELGZERO>:<HRCDID>] 0
    <NAME>:BOUND:1 + <NAME>:BOUND:2 + <NAME>:BULK/DIFFUSING
        <-> <NAME>:LINKER:1 + <NAME>:LINKER:2
    <ONRATE> <OFFRATE> <RMIN> <RMAX>)
```
where NAME is the string name of the species, and ONRATE and OFFRATE are float values that determines the rate constant of the binding and unbinding reactions. RMIN and RMAX are the range of the chemical reaction, and this can be set depending on the structure of the simulated cross-linker. It is noted that the third species listed can be either DIFFUSING or BULK. The bound species listed must be the corresponding cross-linker binding site.

This reaction produces cross-linker species at two separate positions on each respective filament which are chemically and mechanically connected. If mechanical force fields are defined for the cross-linkers, a potential will be created between the filaments. The unbinding reaction will remove these species from the filaments, as well as remove any linker potentials that have been created between the filaments.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A motor reaction between two filaments can be defined in the following form:
```
(MOTORREACTION
    [<DELGZERO>:<HRCDID>] 0
    <NAME>:BOUND:1 + <NAME>:BOUND:2 + <NAME>:BULK/DIFFUSING
        <-> <NAME>:MOTOR:1 + <NAME>:MOTOR:2
    <ONRATE> <OFFRATE> <RMIN> <RMAX>)
```
where NAME is the string name of the species, and ONRATE and OFFRATE are float values that determines the rate constant of the binding and unbinding reactions. RMIN and RMAX are the range of the chemical reaction, and this can be set depending on the structure of the simulated motor. It is noted that the third species listed can be either DIFFUSING or BULK. The bound species listed must be the corresponding motor binding site.

This binding reaction produces motor species at two separate positions on each respective filament which are chemically and mechanically connected. If mechanical force fields are defined for the motor, a potential will be created between the filaments. The unbinding reaction will remove these species from the filaments, as well as remove any motor potentials that have been created between the filaments.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A motor walking reaction can be defined in the following form:
```
(MOTORWALKINGREACTION
    [<DELGZERO>:<HRCDID>] <FILAMENTTYPE>
    <NAME>:MOTOR:N/N+1 + <NAME>:BOUND:N/N+1
        -> <NAME>:MOTOR:N/N+1 + <NAME>:BOUND:N/N+1
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. The choice of N/N+1 will determine whether the motor is stepping forward or backward. A motor movement from N to N+1 is defined as forward movement (towards the plus end of the filament), and the opposite is backward (towards the minus end). These choices for the reactants and products must be self-consistent as well as consistent with the bound species positions chosen in the reaction, or a startup error will result. The bound species listed must be the corresponding motor binding site.

This reaction will move a motor head in the given direction.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A branching reaction can be defined in the following form:
```
(BRANCHINGREACTION
    <FILAMENTTYPE>
    <NAME>:BULK/DIFFUSING + <NAME>:BULK/DIFFUSING + <NAME>:BOUND
        <-> <NAME>:BRANCHER + <NAME>:PLUSEND
    <ONRATE> <OFFRATE> <NUCLEATIONZONE> <NUCLEATIONDIST>)
```
where NAME is the string name of the species, and ONRATE, OFFRATE are float values that determine the rate constants of the reaction. It is noted that the first and second species listed can be either DIFFUSING or BULK. The bound species listed must be the corresponding branching binding site.

The NUCLEATIONZONE and NUCLEATIONDIST specify the volume in which a branching reaction can occur. The choices for the zone parameter are the following
- ALL : A new filament can nucleate anywhere in the simulation volume due to branching.
- BOUNDARY : A new filament can nucleate a given distance away from a boundary due to branching, specified by the NUCLEATIONDIST from the system boundary.
- TOPBOUNDARY : Similar to BOUNDARY except only in the top half of the volume (in the z direction).
It is noted that NUCLEATIONDIST needs to be specified for all nucleation zones, but it is unused for ALL.

This reaction will create a new branching point, as well as a filament with the desired chemical plus end. If mechanical force fields are defined for the branching point, a potential will be created between the parent and child filament. The unbinding reaction will remove the branching point from the filaments, thus freeing the child filament from the parent. It will also remove any branching point potentials that have been created between the filaments.

This reaction does not support dissipation tracking, so HRCDID and DELGZERO should not be provided.
A nucleation reaction can be defined in the following form:
```
(NUCLEATIONREACTION
    <FILAMENTTYPE>
    <NAME>:BULK/DIFFUSING + <NAME>:BULK/DIFFUSING
        -> <NAME>:PLUSEND + <NAME>:FILAMENT + <NAME>:MINUSEND
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. It is noted that the first and second species listed can be either DIFFUSING or BULK.

This reaction will create a new filament with the given chemical plus end, minus end, and filament species. PLEASE REFER TO THE EXAMPLE FILES FOR A COMPLETE NUCLEATION CYCLE.

This reaction does not support dissipation tracking, so HRCDID and DELGZERO should not be provided.
A destruction reaction can be defined in the following form:
```
(DESTRUCTIONREACTION
    <FILAMENTTYPE>
    <NAME>:PLUSEND + <NAME>:MINUSEND -> <NAME>:BULK/DIFFUSING + <NAME>:BULK/DIFFUSING
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. It is noted that the third and fourth species listed can be either DIFFUSING or BULK.

This reaction will destroy a filament, removing it from the system.

This reaction does not support dissipation tracking, so HRCDID and DELGZERO should not be provided.
A filament aging reaction can be defined in the following form:
```
(AGINGREACTION
    [<DELGZERO>:<HRCDID>] <FILAMENTTYPE>
    <NAME>:FILAMENT/PLUSEND/MINUSEND -> <NAME>:FILAMENT/PLUSEND/MINUSEND
    <RATE>)
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction. Either of the reactant or product species can be FILAMENT, PLUSEND, or MINUEND, but the product and reactant species must be the same type, or a startup error will result.

This reaction will change the chemical species that resides in a filament.

This reaction supports dissipation tracking, so if the feature is turned on, then HRCDID should be set to a user specified short unique string, and DELGZERO should be set to a float value based on the user’s parameterization of the chemical energetics.
A filament severing reaction can be defined in the following form:
```
SEVERINGREACTION <FILAMENTTYPE> AT <NAME>:FILAMENT <RATE>
```
where NAME is the string name of the species, and RATE is a float value that determines the rate constant of the reaction.

This reaction will sever the filament at the closest cylinder connection to a given chemical position, producing two child filaments.

This reaction does not support dissipation tracking, so HRCDID and DELGZERO should not be provided.