src/sys_def.jl

`MEDYAN.add_diffusion_coeff!`

add_diffusion_coeff!(s::SysDef, name::Symbol, coeff::Float64)

Update the diffusion coefficient for an existing diffusing species.

The species must already exist in s.diffusing (typically added via add_diffusing_species!.

Arguments

s::SysDef: The system definition to modify.
name::Symbol: The name of the existing diffusing species.
coeff::Float64: The diffusion coefficient in units of nm²/s.

Returns

The modified SysDef.

See also: add_diffusing_species! to add a new species with its diffusion coefficient in one step.

`MEDYAN.add_diffusing_species!`

add_diffusing_species!(s::SysDef, name::Symbol; coeff::Float64)

Dynamically add a new diffusing species to the system definition.

Arguments

s::SysDef: The system definition to modify.
name::Symbol: The name of the new diffusing species.
coeff::Float64: The diffusion coefficient in units of (nm²/s).

Returns

The modified SysDef.

Throws

Error if a diffusing species with the given name already exists.

`MEDYAN.add_fila_type!`

add_fila_type!(s::SysDef; name::Symbol, mono_states::Vector{Symbol}, param::FilamentMechParams)

Add a new filament type to the system definition.

Arguments

s::SysDef: The system definition to modify.
name::Symbol: The name of the new filament type.
mono_states::Vector{Symbol}: Vector of monomer state names for this filament type. Must not be empty.
param::FilamentMechParams: The filament mechanical parameters.

Returns

The modified SysDef.

Throws

Error if a filament type with the given name already exists.
Error if mono_states is empty.

`MEDYAN.add_filament_params!`

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

Update the filament mechanical parameters for an existing filament type.

The filament type must already exist in s.filament (typically added via add_fila_type!.

Arguments

s::SysDef: The system definition to modify.
filament_name::Symbol: The name of the existing filament type.
filament_params::FilamentMechParams: The mechanical parameters to set.

Returns

The modified SysDef.

See also: add_fila_type! to add a new filament type with its parameters in one step.

`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).
- Optional fields:
  - rate = Returns(1.0): 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).
  - 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.

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)).
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

s::SysDef: the system to add to.
filamenttypename::Symbol: the filament type name.
filamentsitename::Symbol: the new name of the filamentsite added. This can be used as a catalyst in other reactions.
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.
center::Int: Which index of changedstatenames.first is the actual location of the filamentsite. Used for determining what compartment the reaction goes in.
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.
rate::Float64: Base rate for the reaction. ((nm³)^(invvolumepower)/s)
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.add_fila_reaction!`

add_fila_reaction!(s::SysDef; fila_type, name, match_states, ...)

Add a filament monomer reaction. The reaction fires at monomers whose local neighborhood matches a pattern of states. When it fires, the matched monomers can be changed to new_states, or a custom affect! callback can handle arbitrary side effects.

All pattern positions must lie on the filament. Monomers near the ends where the pattern would extend past the boundary are automatically skipped. Use add_fila_tip_reaction! for reactions at filament ends.

Keyword Arguments

Required

fila_type::Symbol: Filament type (e.g., :actin).
name::Symbol: Unique name for this reaction site.
match_states::Vector: Pattern of monomer states to match, ordered minus → plus end. Each element can be:
- Symbol — exact state (e.g., :a)
- Vector{Symbol} — any of these states (e.g., [:a, :b])
- anystate — any state

State change (provide exactly one)

new_states::Vector{Symbol}: States to assign to the matched monomers after firing. Must be the same length as match_states. Cannot be used with affect!.
affect!: Custom callback (c::Context; chem_voxel::Int, center::FilaMonoIdx, kwargs...) -> Int. Called instead of automatic state changes. The returned Int is a status code. Cannot be used with new_states.

Rate

base_rate::Float64: Rate constant. Units: (nm³)^invvolumepower / s.
invvolumepower::Int = 0: Set to 0 for unimolecular, 1 for bimolecular.
reactants_extra::String = "": Additional reactant species that contribute to propensity (e.g., "diffusing.ligand"). The species is not consumed automatically.

Geometry

center::Int = cld(length(match_states), 2): Which position in match_states is the center of the reaction. Determines which chem_voxel the reaction is assigned to.

Examples

using MEDYAN
s = MEDYAN.SysDef()
add_fila_type!(s; name=:actin, mono_states=[:a, :b, :c], param=MEDYAN.ACTIN_TWIST_PARAMS)

# Aging: every :a monomer transitions to :b
add_fila_reaction!(s;
    fila_type = :actin, name = :aging,
    match_states = [:a],
    new_states = [:b],
    base_rate = 2.4,
)

# Cooperative transition: :a next to :b on the minus side becomes :b
add_fila_reaction!(s;
    fila_type = :actin, name = :cooperate,
    match_states = [:b, :a],
    new_states = [:b, :b],
    center = 2,
    base_rate = 0.4,
)

# Bimolecular binding with a diffusing ligand
add_diffusing_species!(s, :ligand; coeff=2.5e7)
add_fila_reaction!(s;
    fila_type = :actin, name = :bind,
    match_states = [:a],
    affect! = (c; center, chem_voxel, kwargs...) -> let
        update_fila_mono_state!(c, center, :b)
        add_diffusing_count!(c; species=:ligand, chem_voxel, amount=-1)
        1
    end,
    base_rate = 1e6,
    invvolumepower = 1,
    reactants_extra = "diffusing.ligand",
)

# Match a set of states: :a or :b → :c
add_fila_reaction!(s;
    fila_type = :actin, name = :a_or_b,
    match_states = [[:a, :b]],
    new_states = [:c],
    base_rate = 1.0,
)

# anystate with neighbor constraint: any monomer whose plus neighbor is :a
add_fila_reaction!(s;
    fila_type = :actin, name = :any_then_a,
    match_states = [anystate, :a],
    new_states = [:a, :b],
    center = 2,
    base_rate = 1.0,
)

`MEDYAN.add_fila_tip_reaction!`

add_fila_tip_reaction!(s::SysDef; fila_type, name, is_minus_end, match_states, spacing, ...)

Add a filament tip reaction that fires only at either the plus or minus end of a filament.

This mirrors add_fila_reaction! in API style and rate wiring, but the pattern is anchored at a filament end. new_states may be shorter or longer than match_states to represent depolymerization or polymerization.

match_states and new_states are always ordered from minus end toward plus end. If is_minus_end = true, the pattern is matched against the first length(match_states) monomers; if is_minus_end = false, it is matched against the last length(match_states) monomers.

Keyword Arguments

Required

fila_type::Symbol: Filament type (e.g., :actin).
name::Symbol: Unique name for this tip site.
is_minus_end::Bool: Which filament end to target. true targets the minus end; false targets the plus end.
match_states::Vector: Pattern of monomer states to match (minus → plus order). Elements can be Symbol, Vector{Symbol} (state set), or anystate.
spacing::Float64: Space needed at the filament end for this reaction (nm). This affects a load-force rate factor via exp(-β * spacing * loadforce) where β is 1/kT and loadforce is the external force pushing axially on the end of the filament.

State change (provide exactly one)

new_states::Vector{Symbol}: New monomer states (minus → plus order) for the tip region. If length(new_states) > length(match_states), monomers are added. If length(new_states) < length(match_states), monomers are removed. Cannot be used with affect!.
affect!: Custom callback (c::Context; chem_voxel::Int, tip::FilaTipIdx, kwargs...) -> Int. Called instead of automatic changes. Cannot be used with new_states.

Rate

base_rate::Float64: Rate constant. Units: (nm³)^invvolumepower / s.
invvolumepower::Int = 0: Set to 0 for unimolecular, 1 for bimolecular.
reactants_extra::String = "": Additional reactant species that contribute to propensity (e.g., "diffusing.ligand"). The species is not consumed automatically.
added_monomers::Union{Int, Nothing}: The number of monomers added by the reaction. This is automatically determined if new_states is passed. Each filament has a limited number of monomers that can be added per end

between mechanic solves given by FilamentMechParams.max_num_unmin_end. The filament tip reaction is disabled on tips where the added monomers would cause that limit to be exceeded.

Examples

using MEDYAN
s = MEDYAN.SysDef()
add_fila_type!(s; name=:actin, mono_states=[:a, :plusend, :minusend], param=MEDYAN.ACTIN_TWIST_PARAMS)
add_diffusing_species!(s, :actin_mon; coeff=2.5e7)

# Plus-end polymerization: add one monomer (bimolecular with diffusing actin)
add_fila_tip_reaction!(s;
    fila_type = :actin,
    name = :pp,
    is_minus_end = false,
    match_states = [:a, :plusend],
    spacing = 2.7,
    affect! = (c; tip, chem_voxel, kwargs...) -> begin
        update_fila_mono_state!(c, FilaMonoIdx(c, tip), :a)
        polymerize_fila!(c, tip, :plusend)
        add_diffusing_count!(c; species=:actin_mon, chem_voxel, amount=-1)
        1
    end,
    added_monomers = 1,
    base_rate = 1.93e7,
    invvolumepower = 1,
    reactants_extra = "diffusing.actin_mon",
)

# Minus-end depolymerization: remove one monomer, release actin back to solution
add_fila_tip_reaction!(s;
    fila_type = :actin, name = :dm,
    is_minus_end = true,
    match_states = [:minusend, :a],
    spacing = 0.0,
    affect! = (c; tip, chem_voxel, kwargs...) -> begin
        depolymerize_fila!(c, tip)
        update_fila_mono_state!(c, FilaMonoIdx(c, tip), :minusend)
        add_diffusing_count!(c; species=:actin_mon, chem_voxel, amount=+1)
        1
    end,
    added_monomers = 0,
    base_rate = 1.4,
)

`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

s::SysDef: the system to add to.
filamenttypename::Symbol: the filament type name.
filamentendsitename::Symbol: the new name of the filamentendsite added. This can be used as a catalyst in other reactions.
isminusend::Bool: true if changing the minus end, false if changing the plus end.
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.
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
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.
rate::Float64: Base rate for the reaction. ((nm³)^(invvolumepower)/s)
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.

src/sys_def.jl

Arguments

Returns

Arguments

Returns

Throws

Arguments

Returns

Throws

Arguments

Returns

Keyword Arguments

Example: Membrane-bound NPF cluster

Example good reactionexpr

Arguments

Examples

Keyword Arguments

Required

State change (provide exactly one)

Rate

Geometry

Examples

Keyword Arguments

Required

State change (provide exactly one)

Rate

Examples

Arguments

Examples

Example good `reactionexpr`