biocrnpyler.mechanisms.binding

Classes

`Combinatorial_Cooperative_Binding`([name, ...])	Combinatorial binding mechanism for multiple distinct ligands.
`One_Step_Binding`([name, mechanism_type])	Simple binding mechanism for multiple species without cooperativity.
`One_Step_Cooperative_Binding`([name, ...])	Cooperative binding mechanism for single-step multi-ligand binding.
`Two_Step_Cooperative_Binding`([name, ...])	Sequential cooperative binding mechanism with oligomerization.

class biocrnpyler.mechanisms.binding.Combinatorial_Cooperative_Binding(name='Combinatorial_Cooperative_binding', mechanism_type='cooperative_binding')[source]

Combinatorial binding mechanism for multiple distinct ligands.

A ‘binding’ mechanism where different types of binder molecules can bind to a bindee in various combinations, each with its own cooperativity. This models complex regulatory scenarios where multiple transcription factors or ligands can bind to the same target in different combinations, each producing a distinct complex.

The mechanism generates all possible binding combinations and the reactions between them, considering individual binding affinities and cooperativities for each binder type.

Parameters:

namestr, default=’Combinatorial_Cooperative_binding’: Name identifier for this mechanism instance.
mechanism_typestr, default=’cooperative_binding’: Type classification of this mechanism.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘cooperative_binding’).

See also

One_Step_Cooperative_Binding: Single binder type cooperative binding.
CombinatorialPromoter: Component that uses this mechanism.
Mechanism: Base class for all mechanisms.

Notes

This mechanism is designed for modeling complex regulatory logic where:

Multiple different regulators can bind to the same target
Each regulator can have its own cooperativity (e.g., some bind as dimers, others as monomers)
All possible combinations of bound states are generated
Each transition between states has specific rate constants

The mechanism generates a complete reaction network connecting all possible bound states. For n different binders, this creates 2^n - 1 different complexes (excluding the unbound state).

Required parameters for this mechanism (per binder):

‘kb’: Forward binding rate
‘ku’: Reverse unbinding rate
‘cooperativity’: Number of molecules binding together

This is commonly used for:

Complex promoter regulation with multiple transcription factors
Multi-ligand receptor systems
Combinatorial protein complex assembly

Examples

Model a promoter with two different transcription factors:

>>> A, B = bcp.Species('A'), bcp.Species('B')
>>> AND_promoter = bcp.CombinatorialPromoter(
...     'AND_promoter', [A, B], tx_capable_list=[[A, B]], leak=False)
... AND_assembly = bcp.DNAassembly(
...     'AND', promoter=AND_promoter, rbs='medium', protein='GFP')
... mixture = bcp.ExpressionExtract(
...     name='AND_mixture', components=[AND_assembly],
...     parameter_file=[
...         'mechanisms/binding_parameters.tsv',
...         'mixtures/extract_parameters.tsv',
...     ]
... )
... crn = mixture.compile_crn()

make_cooperative_complex(combo, bindee, cooperativity)[source]

Create a complex with multiple cooperative binders.

Constructs a complex species containing the specified combination of binders (each repeated according to its cooperativity) bound to the bindee.

Parameters:

combotuple or list of Species: Combination of binder species to include in the complex.
bindeeSpecies: The target species being bound to.
cooperativitydict: Dictionary mapping binder names (str) to their cooperativity values (int). Determines how many copies of each binder are included.

Returns:

Species or Complex: If only bindee is present (empty combo), returns bindee alone. Otherwise returns a Complex containing all binders (repeated per cooperativity) and the bindee.

Notes

For each binder in combo, the method adds cooperativity[binder.name] copies to the complex. For example, if binder A has cooperativity 2 and binder B has cooperativity 1, the complex for combo=[A, B] would contain [A, A, B, bindee].

update_reactions(binders, bindee, component=None, kbs=None, kus=None, part_id=None, cooperativity=None, **kwargs)[source]

Generate reactions for all combinatorial binding transitions.

Creates reactions connecting all possible binding states, where each reaction represents one binder type associating or dissociating while other binders remain bound.

Parameters:

binderslist of Species: List of different binder species that can bind in combinations.
bindeeSpecies: The target species being bound to.
componentComponent, optional: Component containing parameter values. Required if rate constants or cooperativities are not provided.
kbsdict, optional: Dictionary mapping binder names to forward rate constants (kb). If None for any binder, retrieved from component parameters.
kusdict, optional: Dictionary mapping binder names to reverse rate constants (ku). If None for any binder, retrieved from component parameters.
part_idstr, optional: Base identifier for parameter lookup. Individual binder parameters are looked up as ‘part_id_bindername’.
cooperativitydict, optional: Dictionary mapping binder names to cooperativity values. If None for any binder, retrieved from component parameters.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Reaction: List of all reactions connecting binding states. Each reaction represents adding or removing one binder type to/from an existing complex.

Raises:

ValueError: If component is None and any required parameters (kb, ku, cooperativity) are not provided.

Notes

The reaction network connects all possible binding states such that:

Each reaction adds or removes exactly one binder type
Rate constants are specific to each binder
Cooperativity determines the stoichiometry of each binder

For n binders, this generates approximately n * 2^(n-1) reactions, connecting the 2^n possible states (including unbound).

Each binder requires three parameters:

‘kb’: Forward binding rate constant
‘ku’: Reverse unbinding rate constant
‘cooperativity’: Stoichiometry of that binder

The algorithm avoids generating duplicate reactions by tracking which transitions have been created.

update_species(binders, bindee, cooperativity=None, component=None, part_id=None, **kwargs)[source]

Generate all species for combinatorial binding.

Creates all possible complexes from combinations of binders bound to the bindee, considering each binder’s cooperativity.

Parameters:

binderslist of Species: List of different binder species that can bind in combinations.
bindeeSpecies: The target species being bound to.
cooperativitydict, optional: Dictionary mapping binder names to cooperativity values. If None for any binder, retrieved from component parameters.
componentComponent, optional: Component containing parameter values. Required if cooperativity values are not provided.
part_idstr, optional: Base identifier for parameter lookup. Individual binder parameters are looked up as ‘part_id_bindername’.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Species: List of all possible complexes from binding combinations. For n binders, returns 2^n - 1 complexes (all combinations except unbound bindee).

Raises:

ValueError: If component is None and cooperativity is not provided for all binders.

Notes

This method generates all possible combinations of binders: - Single binders: A:bindee, B:bindee, etc. - Pairs: A:B:bindee, A:C:bindee, etc. - Higher combinations up to all binders bound simultaneously

Each complex respects the individual cooperativity of its binders.

class biocrnpyler.mechanisms.binding.One_Step_Binding(name='one_step_binding', mechanism_type='binding')[source]

Simple binding mechanism for multiple species without cooperativity.

A ‘binding’ mechanism to model the simultaneous binding of multiple species into a single complex in one concerted step. Unlike cooperative binding mechanisms, this treats all species equally without cooperativity factors - each species contributes exactly one molecule to the complex.

The binding reaction follows: S1 + S2 + … + Sn <–> S1:S2:…:Sn

Parameters:

namestr, default=’one_step_binding’: Name identifier for this mechanism instance.
mechanism_typestr, default=’binding’: Type classification of this mechanism.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘binding’).

See also

One_Step_Cooperative_Binding: Binding with cooperativity.
Mechanism: Base class for all mechanisms.

Notes

This mechanism is the simplest binding model where multiple distinct species come together to form a complex. Each species contributes exactly one molecule (stoichiometry of 1) to the complex.

Common applications include:

Protein complex formation from distinct subunits
Multi-component enzyme assembly
Simple receptor-ligand binding
Formation of heterodimers or heterotrimers

The mechanism generates a single reversible mass-action reaction with rate constants ‘kb’ (forward) and ‘ku’ (reverse).

Key differences from cooperative binding:

No ‘cooperativity’ parameter - all stoichiometries are 1
Can handle arbitrary lists of different species
Simpler parameter structure (single ‘kb’, ‘ku’ for the entire reaction)

Required parameters for this mechanism:

‘kb’ : Forward binding rate constant
‘ku’ : Reverse unbinding rate constant

Examples

Model receptor-ligand binding:

>>> mech = bcp.One_Step_Binding()
>>> ligand, receptor = bcp.Species('L'), bcp.Species('R')
>>> mech.update_species(
...     binder=ligand,
...     bindee=receptor,
...     kb=1.0, ku=0.001
... )
[L, R, complex_L_R_]

Model formation of a three-protein complex:

>>> proteins = [
...     bcp.Species(s, material_type='protein') for s in ['A', 'B', 'C']]
>>> rxns = mech.update_reactions(
...     binder=proteins[0],
...     bindee=proteins[1:],
...     kb=0.1, ku=0.01
... )
>>> # Generates: A + B + C <--> A:B:C

update_reactions(binder, bindee, component=None, complex_species=None, part_id=None, kb=None, ku=None, **kwargs)[source]

Generate reaction for simple multi-species binding.

Creates a single reversible mass-action reaction for the binding of all species into a complex.

Parameters:

binderSpecies or list of Species: The first species or list of species to bind. Automatically converted to list if single species provided.
bindeeSpecies or list of Species: The second species or list of species to bind. Automatically converted to list if single species provided.
componentComponent, optional: Component containing parameter values. Required if kb or ku are not provided directly.
complex_speciesSpecies, optional: Pre-specified complex species. If None, automatically creates a Complex containing all binders and bindees.
part_idstr, optional: Identifier for parameter lookup. If None, automatically generated from species names as name1_name2_..._nameN.
kbParameter or float, optional: Forward binding rate constant. If None, retrieved from component parameters.
kuParameter or float, optional: Reverse unbinding rate constant. If None, retrieved from component parameters.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Reaction: List containing a single reversible mass-action reaction for the binding of all species.

Raises:

ValueError: If component is None and kb or ku is not provided.

Notes

The reaction has equal stoichiometry (1) for all species: species1 + species2 + … + speciesN <–> complex

This is simpler than cooperative binding mechanisms which can have varying stoichiometries for different species.

update_species(binder, bindee, component=None, complex_species=None, part_id=None, **kwargs)[source]

Generate species for simple multi-species binding.

Creates the list of species involved in the binding reaction: all input species plus the resulting complex.

Parameters:

binderSpecies or list of Species: The first species or list of species to bind. Automatically converted to list if single species provided.
bindeeSpecies or list of Species: The second species or list of species to bind. Automatically converted to list if single species provided.
componentComponent, optional: Component containing this mechanism (unused but kept for API consistency).
complex_speciesSpecies, optional: Pre-specified complex species. If None, automatically creates a Complex containing all binders and bindees.
part_idstr, optional: Identifier for parameter lookup. If None, automatically generated from species names as name1_name2_..._nameN.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Species: List containing all input species plus the complex. Format: [binder1, …, bindee1, …, complex].

Notes

The binder/bindee distinction is primarily for API consistency with other binding mechanisms. Functionally, all species are treated equally in the binding reaction.

The complex is created as a Complex object containing all input species in the order: binders + bindees.

class biocrnpyler.mechanisms.binding.One_Step_Cooperative_Binding(name='one_step_cooperative_binding', mechanism_type='cooperative_binding')[source]

Cooperative binding mechanism for single-step multi-ligand binding.

A ‘binding’ mechanism where multiple copies of a binder molecule (A) bind cooperatively to a single bindee molecule (B) in one concerted step. This models cooperative binding events where all ligands bind simultaneously rather than sequentially.

The binding reaction is given by

n*A + B <–> A_n:B

where n is the cooperativity (number of binders).

Parameters:

namestr, default=’one_step_cooperative_binding’: Name identifier for this mechanism instance.
mechanism_typestr, default=’cooperative_binding’: Type classification of this mechanism.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘cooperative_binding’).

See also

Two_Step_Cooperative_Binding: Sequential cooperative binding mechanism.
Combinatorial_Cooperative_Binding: Multiple distinct binders binding.
One_Step_Binding: Simple binding without cooperativity.
Mechanism: Base class for all mechanisms.

Notes

This mechanism is used to model cooperative binding where multiple identical ligands bind simultaneously to a receptor. Common examples include:

Oxygen binding to hemoglobin
Transcription factor dimers binding to DNA
Cooperative enzyme-substrate interactions

The mechanism generates a single reversible mass-action reaction with forward rate constant ‘kb’ and reverse rate constant ‘ku’. The ‘cooperativity’ parameter determines the stoichiometry of the binding reaction. A cooperativity of 2 models dimeric binding, 3 for trimeric, etc.

Required parameters for this mechanism:

‘kb’ : Forward binding rate constant
‘ku’ : Reverse unbinding rate constant
‘cooperativity’ : Number of binder molecules that bind simultaneously

Examples

Create a mechanism for dimeric transcription factor binding:

>>> promoter = bcp.RegulatedPromoter(
...     name='p_dimer',
...     regulators='TF_dimer',
... )
>>> mixture = bcp.Mixture(
...     components=[promoter],
...     mechanisms={'binding': bcp.One_Step_Cooperative_Binding()},
...     parameters={'cooperativity': 2, 'kb': 0.1, 'ku': 0.01}
... )

update_reactions(binder, bindee, complex_species=None, component=None, kb=None, ku=None, part_id=None, cooperativity=None, **kwargs)[source]

Generate reactions for cooperative binding.

Creates a single reversible mass-action reaction for the cooperative binding of multiple binder molecules to a bindee.

Parameters:

binderSpecies: The ligand species that binds cooperatively.
bindeeSpecies: The target species being bound to.
complex_speciesSpecies, optional: Pre-specified complex species. If None, automatically creates a Complex containing n binders and 1 bindee.
componentComponent, optional: Component containing parameter values. Required if kb, ku, or cooperativity are not provided directly.
kbParameter or float, optional: Forward binding rate constant. If None, retrieved from component parameters.
kuParameter or float, optional: Reverse unbinding rate constant. If None, retrieved from component parameters.
part_idstr, optional: Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.
cooperativityint or float, optional: Number of binder molecules that bind simultaneously. If None, retrieved from component parameters.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Reaction: List containing a single reversible mass-action reaction for cooperative binding.

Raises:

ValueError: If component is None and any of kb, ku, or cooperativity is not provided.
TypeError: If complex_species is not a Species or None.

Notes

The reaction stoichiometry is determined by the cooperativity parameter:

cooperativity * binder + bindee <–> complex

The forward rate is kb and reverse rate is ku. The reaction follows mass-action kinetics with the appropriate stoichiometric coefficients.

update_species(binder, bindee, complex_species=None, cooperativity=None, component=None, part_id=None, **kwargs)[source]

Generate species for cooperative binding.

Creates the species involved in cooperative binding: the binder, bindee, and the resulting complex containing multiple binders bound to the bindee.

Parameters:

binderSpecies: The ligand species that binds cooperatively.
bindeeSpecies: The target species being bound to.
complex_speciesSpecies, optional: Pre-specified complex species. If None, automatically creates a Complex containing n binders and 1 bindee, where n is the cooperativity.
cooperativityint or float, optional: Number of binder molecules that bind simultaneously. If None, retrieved from component parameters using part_id.
componentComponent, optional: Component containing parameter values. Required if cooperativity is not provided directly.
part_idstr, optional: Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Species: List containing [binder, bindee, complex] where complex is the cooperative binding product.

Raises:

ValueError: If neither component nor cooperativity is provided.
TypeError: If complex_species is not a Species or None.

Notes

The cooperativity parameter determines how many binder molecules are incorporated into the complex. For example, cooperativity=2 creates a complex with 2 binders and 1 bindee.

class biocrnpyler.mechanisms.binding.Two_Step_Cooperative_Binding(name='two_step_cooperative_binding', mechanism_type='cooperative_binding')[source]

Sequential cooperative binding mechanism with oligomerization.

A ‘binding’ mechanism where multiple binder molecules first oligomerize, then the oligomer binds to the bindee in a two-step process. This models cooperative binding where ligands must first form a multimeric complex before binding to their target.

The binding process follows two sequential reactions:

n*A <–> A_n (oligomerization)
A_n + B <–> A_n:B (binding)

where n is the cooperativity.

Parameters:

namestr, default=’two_step_cooperative_binding’: Name identifier for this mechanism instance.
mechanism_typestr, default=’cooperative_binding’: Type classification of this mechanism.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘cooperative_binding’).

See also

One_Step_Cooperative_Binding: Single-step cooperative binding.
Combinatorial_Cooperative_Binding: Multiple distinct binders.
Mechanism: Base class for all mechanisms.

Notes

This mechanism models cooperative binding as a two-step process:

Oligomerization: Binder molecules first associate to form an oligomer (dimer, trimer, etc.)
Binding: The oligomer then binds to the target

This is useful for modeling:

Protein dimerization followed by DNA binding
Receptor oligomerization before ligand binding
Sequential assembly and binding processes

Required parameters for this mechanism:

‘kb1’ : Forward rate constant for oligomerization
‘ku1’ : Reverse rate constant for oligomerization
‘kb2’ : Forward rate constant for oligomer-bindee binding
‘ku2’ : Reverse rate constant for oligomer-bindee binding
‘cooperativity’ : Number of binder molecules in the oligomer

Examples

Model transcription factor dimerization followed by DNA binding:

>>> mech = bcp.Two_Step_Cooperative_Binding()
>>> # TF dimerizes (2*TF <-> TF2), then binds DNA (TF2 + DNA <-> TF2:DNA)
>>> params = {
...     'cooperativity': 2,
...     'kb1': 0.1, 'ku1': 0.01,  # Dimerization rates
...     'kb2': 1.0, 'ku2': 0.001   # DNA binding rates
... }

Model trimeric receptor assembly and activation:

>>> mech = bcp.Two_Step_Cooperative_Binding()
>>> params = {
...     'cooperativity': 3,  # Trimeric receptor
...     'kb1': 0.05, 'ku1': 0.1,   # Trimerization
...     'kb2': 10.0, 'ku2': 0.01   # Ligand binding
... }

update_reactions(binder, bindee, kb=None, ku=None, component=None, part_id=None, cooperativity=None, complex_species=None, n_mer_species=None, **kwargs)[source]

Generate reactions for two-step cooperative binding.

Creates two sequential reactions: oligomerization of binders followed by oligomer binding to the bindee.

Parameters:

binderSpecies: The ligand species that oligomerizes then binds.
bindeeSpecies: The target species that the oligomer binds to.
kblist of float or Parameter, optional: Forward rate constants [kb1, kb2] for oligomerization and binding. If None, retrieved from component parameters.
kulist of float or Parameter, optional: Reverse rate constants [ku1, ku2] for oligomerization and binding. If None, retrieved from component parameters.
componentComponent, optional: Component containing parameter values. Required if kb, ku, or cooperativity are not provided.
part_idstr, optional: Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.
cooperativityint or float, optional: Number of binders in the oligomer. If None, retrieved from component parameters.
complex_speciesSpecies, optional: Pre-specified final complex species.
n_mer_speciesSpecies, optional: Pre-specified oligomer species.
**kwargs: Additional keyword arguments passed to update_species.

Returns:

list of Reaction

List containing two reactions:

Oligomerization: cooperativity*binder <–> n_mer
Binding: n_mer + bindee <–> complex

Raises:

ValueError: If component is None and kb, ku, or cooperativity is not provided, or if kb and ku do not contain exactly 2 values each.

Notes

The two-step process uses separate rate constants:

‘kb1’, ‘ku1’: Control oligomerization kinetics
‘kb2’, ‘ku2’: Control oligomer-bindee binding kinetics

This separation allows modeling of processes where oligomerization and binding have different kinetic properties.

update_species(binder, bindee, component=None, complex_species=None, n_mer_species=None, cooperativity=None, part_id=None, **kwargs)[source]

Generate species for two-step cooperative binding.

Creates the species involved in sequential cooperative binding: binder, bindee, oligomer (n-mer), and final complex.

Parameters:

binderSpecies: The ligand species that oligomerizes then binds.
bindeeSpecies: The target species that the oligomer binds to.
componentComponent, optional: Component containing parameter values. Required if cooperativity is not provided directly.
complex_speciesSpecies, optional: Pre-specified final complex species. If None, automatically creates a Complex containing the n-mer and bindee.
n_mer_speciesSpecies, optional: Pre-specified oligomer species. If None, automatically creates a Complex containing n binders.
cooperativityint or float, optional: Number of binders in the oligomer. If None, retrieved from component parameters.
part_idstr, optional: Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.
**kwargs: Additional keyword arguments (unused).

Returns:

list of Species: List containing [binder, bindee, complex, n_mer] where n_mer is the oligomer and complex is the final bound product.

Raises:

ValueError: If neither component nor cooperativity is provided.
TypeError: If n_mer_species or complex_species is not a Species or None.

Notes

The n_mer represents the oligomerized form of the binder (e.g., a dimer for cooperativity=2). The complex represents the n_mer bound to the bindee.