MEDYAN.add_link_type!

Tuple{MEDYAN.SysDef}

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
            ),
        ],
    ],
)