Skip to content

API Reference

System

System

Equilibrium concentration solver for nucleic acid strand systems.

Build a system by chaining monomer() and complex() calls, then call equilibrium() to solve for equilibrium concentrations.

Parameters:

Name Type Description Default
temperature_C float

Temperature in degrees Celsius (default: 25.0).

 required
temperature_K float

Temperature in kelvin. Cannot be combined with temperature_C.

 required

Examples:

>>> import equiconc
>>> eq = (equiconc.System()
...     .monomer("A", 100e-9)
...     .monomer("B", 100e-9)
...     .complex("AB", [("A", 1), ("B", 1)], dg_st=-10.0)
...     .equilibrium())
>>> eq["AB"] > 0
True

monomer(name, total_concentration) method descriptor

Add a monomer species with a given total concentration.

Parameters:

Name Type Description Default
name str

Name of the monomer species. Must be unique and non-empty.

 required
total_concentration float

Total concentration in molar (mol/L). Must be finite and positive.

 required

Returns:

Type Description
System

The same system instance, for method chaining.

complex(name, composition, *, dg_st=None, delta_g_over_rt=None, dh_st=None, ds_st=None) method descriptor

Add a complex species with a given stoichiometry and energy.

Exactly one energy specification must be provided:

  • dg_st: standard free energy of formation in kcal/mol
  • dg_st=(value, temperature_C) + ds_st: ΔG at a known temperature plus ΔS; ΔH is derived as ΔH = ΔG + T·ΔS and ΔG at the system temperature is computed as ΔH − T_sys·ΔS
  • delta_g_over_rt: dimensionless ΔG/RT (no temperature needed)
  • dh_st + ds_st: enthalpy (kcal/mol) and entropy (kcal/(mol·K)); ΔG is computed as ΔH − TΔS at solve time

Parameters:

Name Type Description Default
name str

Name of the complex. Must be unique across all species.

 required
composition list of (str, int)

Monomer composition as [(monomer_name, count), ...]. Each monomer must have been previously added and count must be >= 1.

 required
dg_st float or (float, float)

Standard free energy of formation in kcal/mol at 1 M standard state. Either a scalar (must be finite), or a tuple (dg_st, temperature_C) giving ΔG at a known temperature in °C; the latter form requires ds_st.

 None
delta_g_over_rt float

Dimensionless free energy ΔG/(RT). When all complexes use this form, temperature is not required.

 None
dh_st float

Enthalpy of formation in kcal/mol. Must be paired with ds_st.

 None
ds_st float

Entropy of formation in kcal/(mol·K). Must be paired with dh_st, or with the tuple form of dg_st.

 None

Returns:

Type Description
System

The same system instance, for method chaining.

equilibrium() method descriptor

Solve for equilibrium concentrations.

Returns:

Type Description
Equilibrium

The result containing concentrations of all species.

Raises:

Type Description
ValueError

If the system specification is invalid (no monomers, unknown monomers in complexes, invalid concentrations, etc.).
RuntimeError

If the solver fails to converge.

Equilibrium

Equilibrium

Result of an equilibrium concentration calculation.

Supports dict-like access: eq["A"], "A" in eq, len(eq), and iteration over species names with for name in eq.

Attributes:

Name Type Description
monomer_names list of str

Monomer species names, in addition order.
complex_names list of str

Complex species names, in addition order.
free_monomer_concentrations list of float

Free monomer concentrations in molar, in addition order.
complex_concentrations list of float

Complex concentrations in molar, in addition order.
converged_fully bool

Whether the solver achieved full convergence. False if the solver accepted results at a relaxed tolerance.

monomer_names property

Monomer names as a list.

complex_names property

Complex names as a list.

free_monomer_concentrations property

Free monomer concentrations as a list.

complex_concentrations property

Complex concentrations as a list.

converged_fully property

Whether the solver achieved full convergence.

False if the solver accepted the result at a relaxed tolerance due to stagnation at f64 precision limits.

concentration(name) method descriptor

Look up a concentration by species name.

Parameters:

Name Type Description Default
name str

Species name (monomer or complex).

 required

Returns:

Type Description
float

Concentration in molar.

Raises:

Type Description
KeyError

If the species name is not found.

to_dict() method descriptor

Convert to a dict mapping species names to concentrations.

Returns:

Type Description
dict

{name: concentration} in deterministic order (monomers first, then complexes, in addition order).

keys() method descriptor

Species names in deterministic order.

Returns:

Type Description
list of str

Names in order: monomers first, then complexes.

values() method descriptor

Concentrations in deterministic order.

Returns:

Type Description
list of float

Concentrations in molar, monomers first, then complexes.

items() method descriptor

(name, concentration) pairs in deterministic order.

Returns:

Type Description
list of (str, float)

Pairs in order: monomers first, then complexes.