src/sys_def.jl

MEDYAN.add_diffusion_coeff!

add_diffusion_coeff!(s::SysDef, diffusing_name::Symbol, diffusing_coeff::Float64)

Add the diffusing species to the system with diffusion coefficent in units of (nm²/s). Return s.

MEDYAN.add_filament_params!

add_filament_params!(s::SysDef, filament_name::Symbol, filament_params::FilamentMechParams)

Add the filament parameters to the system. Return s.

See MEDYAN.FilamentMechParams

MEDYAN.addfilamentsite!

addfilamentsite!(s::SysDef,filamenttypename::Symbol,filamentsitename::Symbol,site)

MEDYAN.addfilamentendsite!

addfilamentendsite!(s::SysDef,filamenttypename::Symbol,filamentendsitename::Symbol,site)::SysDef

MEDYAN.add_decimated_2mon_site!

add_decimated_2mon_site!(s::SysDef,decimated_2mon_sitename::Symbol,site)::SysDef

MEDYAN.addpossiblecadherinsite!

addpossiblecadherinsite!(s::SysDef,possiblecadherinsitename::Symbol,site)::SysDef

MEDYAN.addmembranesite!

addmembranesite!(
    s::MEDYAN.SysDef,
    membranesitename::Symbol,
    site
) -> MEDYAN.SysDef

Add a new site with a specified name. During this process, a new fixed species is created suffixed with “membranesite.”.

MEDYAN.add_link_type!

add_link_type!(s::SysDef; name, description, places, bonds, reactions, param, state)::SysDef

Add a new link type to the system definition. Links represent connections between simulation elements (filament monomers, filament tips, anchors, membrane vertices) that can have associated mechanical bonds and chemical reactions.

Keyword Arguments

• name::Symbol: Unique identifier for this link type.

• description::String="": Human-readable description of the link’s purpose.

• places::Vector{<:Place}: The places this link connects. Each place can be:

  • FilaMonoIdx(): A filament monomer
  • FilaTipIdx(): A filament tip (plus or minus end)
  • Anchor(): A free-floating anchor point (e.g., membrane-bound protein)
  • BallIdx(): A ball (spherical object)
  • MembVertIdx(): A membrane vertex

• bonds::Vector: Mechanical bonds between places. Each bond is a NamedTuple with:

  • bond: Bond type (e.g., DistanceRestraint(), custom Bond subtype)
  • input::Tuple{Int...}: Which places the bond connects
  • param::NamedTuple: Fixed parameters (e.g., spring constant k)
  • state::NamedTuple: Mutable state (e.g., rest length L0)
  • enabled::Bool=true: Whether bond is active by default

• reactions::Vector{Vector}: Reactions at each place. Each reaction is a NamedTuple:

  • Required fields:

    • name::Symbol: Unique identifier for this reaction within the place.
    • affect!: Callback (c::Context; link, chem_voxel, reaction_id, place_idx, kwargs...) -> Int that executes the reaction. Return 1 on success, 0 to reject. For fila_cutoff reactions, also receives place (the nearby filament monomer).
    • rate: Function (c::Context; link, link_data, place_idx, link_state, kwargs...) -> Float64 returning the state-dependent rate factor. For multi-site binding, return the number of available sites (e.g., NPF_MAX_ACTIN - link_state.num_actin).

  • Optional fields:

    • base_rate::Float64 = 1.0: Rate constant multiplier. For bimolecular reactions with invvolumepower=1, use units of nm³/s (e.g., diffusion-limited rate k_D = 4πDR ≈ 1.57×10⁹ nm³/s for D=25 μm²/s, R=5 nm). Separating large rate constants from small integer multipliers in rate avoids overflow.
    • invvolumepower::Int64 = 0: Volume scaling. Set to 1 for bimolecular (nm³/s), 0 for unimolecular (1/s).
    • reactants_extra::String = "": Additional reactants like "diffusing.ARP23". Makes propensity proportional to these species counts.
    • fila_cutoff::Tuple{Symbol, Float64} = nothing: If set, e.g., (:actin, 50.0), rate is multiplied by nearby filament monomers within cutoff (nm), and affect! receives one such monomer as place.
    • enabled::Bool = true: Whether reaction is active by default.

• param::NamedTuple=(;): Fixed parameters for the link type.

• state::NamedTuple=(;): Initial mutable state (e.g., (num_bound=Int32(0),)).

Example: Membrane-bound NPF cluster

MEDYAN.add_link_type!(s;
    name=:npf_anchor,
    description="Nucleation promoting factor anchored to membrane",
    places=[Anchor()],
    state=(;
        num_arp23 = Int32(0),  # bound ARP2/3 count
        num_actin = Int32(0),  # bound actin count
    ),
    reactions=[
        [
            # Bimolecular binding: NPF + diffusing ARP2/3 → NPF·ARP2/3
            (;
                name = :arp23_bind,
                affect! = (c; link, chem_voxel, kwargs...) -> let
                    link_state = get_state(c, link)
                    update_link!(c, link; state=(num_arp23=link_state.num_arp23 + Int32(1),))
                    add_diffusing_count!(c; species=:ARP23, chem_voxel, amount=-1)
                    1
                end,
                rate = (c; link_state, kwargs...) -> NPF_MAX_ARP23 - link_state.num_arp23,
                base_rate = 5E7,  # nm³/s
                reactants_extra = "diffusing.ARP23",
                invvolumepower = 1,
            ),
            # Unimolecular unbinding: NPF·ARP2/3 → NPF + ARP2/3
            (;
                name = :arp23_unbind,
                affect! = (c; link, chem_voxel, kwargs...) -> let
                    link_state = get_state(c, link)
                    update_link!(c, link; state=(num_arp23=link_state.num_arp23 - Int32(1),))
                    add_diffusing_count!(c; species=:ARP23, chem_voxel, amount=+1)
                    1
                end,
                rate = (c; link_state, kwargs...) -> link_state.num_arp23,
                base_rate = 0.01,  # 1/s per bound ARP2/3
            ),
        ],
    ],
)

MEDYAN.addreaction!

addreaction!(s::SysDef,reaction::CompartmentReaction)::SysDef

addreaction!(s::SysDef,reactionexpr::AbstractString,rate::Float64,invvolumepower::Int)::SysDef

Add a reaction to the system. Return s

reactionexpr is a string describing the reaction stoichiometry

reactionexpr is comprised of reactant and product parts seperated by a "-->"

All whitespace characters are ignored.

Each side is then split by "+" to get the species names.

Repeated or extra "+" are ignored.

A species name can be prepended by a positive integer to represent multiple copies.

1. rate::Float64: Base rate for the reaction. ((nm³)^(invvolumepower)/s) rate constants correspond to stochastic rate constants in the sense used by Gillespie (J. Comp. Phys., 1976, 22 (4)).
2. invvolumepower::Int: volumefactor= (1/volume)^invvolumepower where volume is the volume of the compartment in nm³. Generally this is 0 for reactions without another diffusing reactant, and 1 if there is another diffusing reactant.

Example good reactionexpr

"diffusing.a + diffusing.b --> diffusing.c"
"diffusing.c --> diffusing.a + diffusing.b"
"+ + diffusing.c + --> + diffusing.a + + diffusing.b + +"
" --> diffusing.a + diffusing.b"
"diffusing.a + diffusing.b --> "
"diffusing.a + diffusing.a --> "
"2diffusing.a --> "
"2diffusing.a --> 20diffusing.a"
"diffusing.c + diffusing.b --> diffusing.c + diffusing.b"
"fixedspecies.rate1b --> fixedspecies.g"
"fixedspecies.rate1b + fixedspecies.g --> fixedspecies.g"
"fixedspecies.rate1b + 23fixedspecies.g --> fixedspecies.g"
"fixedspecies.g --> fixedspecies.rate1b + 23fixedspecies.g"
"fixedspecies.g + fixedspecies.rate1b--> 2fixedspecies.rate1b + 23fixedspecies.g"
"filamentsite.MT.d --> filamentsite.MT.d"
"filamentsite.MT.d + diffusing.a --> filamentsite.MT.d"
"fixedspecies.g --> diffusing.a"
"diffusing.a --> fixedspecies.g"
"filamentsite.actin.pm + diffusing.a --> filamentsite.actin.pm"

MEDYAN.addreactioncallback!

addreactioncallback!(s::SysDef, reaction::CompartmentReaction, callback)::SysDef
addreactioncallback!(s::SysDef, reactantexpr::AbstractString, rate::Float64, invvolumepower::Int, callback)::SysDef

Like addreaction! but also adds callback. callback is called when the reaction happens with input of MEDYAN.Context and Int the compartment id where the reaction happened.

The reaction should normally have no net stoichiometry because the callback should handle updating species counts. If an AbstractString is passed instead of a CompartmentReaction for the reaction, that string will be parsed to determine the reactants. The net stoichiometry will be zero.

MEDYAN.errorcheck_addcallback(callback,s::SysDef) can optionally be overloaded to add errorchecking when the callback is added.

Callback for bulk reactions: Context -> Nothing.

MEDYAN.addfilament_reaction!

Add filament reaction. Return s. Add a filamentsite and reaction with callback to change the monomer state. This can be used for filament aging, filament catalyzed reactions, or simple binding reactions.

Arguments

1. s::SysDef: the system to add to.
2. filamenttypename::Symbol: the filament type name.
3. filamentsitename::Symbol: the new name of the filamentsite added. This can be used as a catalyst in other reactions.
4. changedstatenames::Pair{Vector{Symbol}, Vector{Symbol}}: the changes to the monomer states, the first is the states to match. The second is the new monomer states after the reaction. both should be the same length. Ordered minus end first.
5. center::Int: Which index of changedstatenames.first is the actual location of the filamentsite. Used for determining what compartment the reaction goes in.
6. reactantexpr::AbstractString: Allows adding other reactants or products to the reaction. " + filamentsite.$(filamenttypename).$(filamentsitename) + " gets added to both sides this to create the full reaction expression. See addreaction! for syntax.
7. rate::Float64: Base rate for the reaction. ((nm³)^(invvolumepower)/s)
8. invvolumepower::Int: volumefactor= (1/volume)^invvolumepower where volume is the volume of the compartment in nm³. volumefactor only applies to this reaction not any other reaction using filamentsitename Generally this is 0 for reactions without another diffusing reactant, and 1 if there is another diffusing reactant.

Examples

using MEDYAN
agent_names = AgentNames(
    filamentnames= [(:filname,[
                            :a,
                            :b,
                            :c,
                        ]),
    ],
)
s= SysDef(agent_names)
addfilament_reaction!(s, :filname, :ab,
    [:a]=>[:b], 1,
    "-->", 1.75E-3, 0,
)
addfilament_reaction!(s, :filname, :aabc,
    [:a,:a]=>[:b,:c], 2,
    "-->", 1.75E-3, 0,
)

MEDYAN.addfilamentend_reaction!

Add filament end reaction. Return s. Add a filamentendsite and reaction with callback to change the filaments. This can be used for polymerization, depolymeriation, and changing end state.

Arguments

1. s::SysDef: the system to add to.
2. filamenttypename::Symbol: the filament type name.
3. filamentendsitename::Symbol: the new name of the filamentendsite added. This can be used as a catalyst in other reactions.
4. isminusend::Bool: true if changing the minus end, false if changing the plus end.
5. changedendstatenames::Pair{Vector{Symbol}, Vector{Symbol}}: the changes to the end monomer states, the first is the states to match. The second is the new monomer states after the reaction. If the second has more states than the first, new monomers will be added, if the second has less, monomers will be removed. Ordered minus end first.
6. spacing::Float64: Space needed at the filament end for this reaction. (nm) ratefactor= exp(-β*spacing*loadforce) where β is 1/kT, loadforce is the external force pushing axially on the end of the filament. and ratefactor affects this reaction propensity and any others using filamentendsitename
7. reactionexpr::AbstractString: Allows adding other reactants or products to the reaction. " + filamentendsite.$(filamenttypename).$(filamentendsitename) + " gets added to both sides this to create the full reaction expression. See addreaction! for syntax.
8. rate::Float64: Base rate for the reaction. ((nm³)^(invvolumepower)/s)
9. invvolumepower::Int: volumefactor= (1/volume)^invvolumepower where volume is the volume of the voxel in nm³. volumefactor only applies to this reaction not any other reaction using filamentendsitename Generally this is 0 for reactions without another diffusing reactant, and 1 if there is another diffusing reactant.

Examples

using MEDYAN
agent_names = AgentNames(
    diffusingspeciesnames= [:a,],
    filamentnames= [(:filname,[
                            :plus,
                            :mid,
                            :minus,
                        ]),
    ],
)
s= SysDef(agent_names)
monomerspacing= 2.7
#minus end polymerization
addfilamentend_reaction!(s, :filname, :pm, true,
    [:minus]=>[:minus,:mid], monomerspacing,
    "diffusing.a -->", 10E3, 1,
)
#plus end depolymerization
addfilamentend_reaction!(s, :filname, :dpp, false,
    [:mid,:plus]=>[:plus], 0.0,
    "--> diffusing.a", 1.75E-3, 0,
)

MEDYAN.add_membranesitereaction!

Add a membrane site with the corresponding reaction with callback.

Keyword arguments:

• s: SysDef.
• name_newmembranesite: Symbol.
• membranediffusingreactants: Vector of symbols as membrane reactants. 0 or 1 reactant is currently supported.
• membranediffusingproducts: Vector of symbols as membrane products.
• reactionexpr_extra: Reaction expression for other species involved.
• rate: Float.
• changerage_bypotentialenergy: Whether the rate is affected by potential energy.
• invvolumepower: rate scaling with compartment volume.

Notes:

• If error occurs, this function does not ensure that s is unchanged.