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.

SolverOptions¶

`SolverOptions` ¶

Solver configuration: tolerances, iteration caps, trust-region parameters, and numerical clamps.

All fields have sensible defaults matching the built-in solver behavior. Construct with keyword arguments and pass to System(options=...).

Parameters:

Name	Type	Description	Default
`max_iterations`	`int`	Maximum outer Newton iterations (default: 1000).	required
`gradient_abs_tol`	`float`	Full-convergence gradient tolerances (default: 1e-22, 1e-7).	required
`gradient_rel_tol`	`float`	Full-convergence gradient tolerances (default: 1e-22, 1e-7).	required
`relaxed_gradient_abs_tol`	`float`	Relaxed tolerances used by the stagnation recovery path (default: 1e-14, 1e-4).	required
`relaxed_gradient_rel_tol`	`float`	Relaxed tolerances used by the stagnation recovery path (default: 1e-14, 1e-4).	required
`stagnation_threshold`	`int`	Consecutive non-reducing iterations before stagnation recovery fires (default: 3).	required
`initial_trust_region_radius`	`float`	Trust-region radius bounds (default: 1.0, 1e10).	required
`max_trust_region_radius`	`float`	Trust-region radius bounds (default: 1.0, 1e10).	required
`step_accept_threshold`	`float`	Minimum ρ for a step to be accepted (default: 1e-4).	required
`trust_region_shrink_rho`	`float`	ρ thresholds for shrinking / growing the trust region (default: 0.25, 0.75).	required
`trust_region_grow_rho`	`float`	ρ thresholds for shrinking / growing the trust region (default: 0.25, 0.75).	required
`trust_region_shrink_scale`	`float`	Multipliers applied to δ on shrink / grow (default: 0.25, 2.0).	required
`trust_region_grow_scale`	`float`	Multipliers applied to δ on shrink / grow (default: 0.25, 2.0).	required
`log_c_clamp`	`float`	Upper bound on `log_q + Aᵀλ` before exp() (default: 700.0).	required
`log_q_clamp`	`float or None`	Optional upper bound on `log_q = -ΔG/RT` applied at construction time (default: None).	required
`objective`	`str`	Trust-region objective surface: `"linear"` (default) minimizes the convex Dirks dual `f(λ)` directly; `"log"` minimizes `g(λ) = ln f(λ)`. The log path can converge in many fewer iterations on stiff systems (very strong binding, asymmetric `c⁰`) but is non-convex; equiconc handles the resulting indefinite Hessians via on-the-fly modified-Cholesky regularization. The mass-conservation convergence test is identical for both. Default: `"linear"`.	required

doc = 'Solver configuration: tolerances, iteration caps, trust-region\nparameters, and numerical clamps.\n\nAll fields have sensible defaults matching the built-in solver\nbehavior. Construct with keyword arguments and pass to\n``System(options=...)``.\n\nParameters\n----------\nmax_iterations : int, optional\n Maximum outer Newton iterations (default: 1000).\ngradient_abs_tol, gradient_rel_tol : float, optional\n Full-convergence gradient tolerances (default: 1e-22, 1e-7).\nrelaxed_gradient_abs_tol, relaxed_gradient_rel_tol : float, optional\n Relaxed tolerances used by the stagnation recovery path\n (default: 1e-14, 1e-4).\nstagnation_threshold : int, optional\n Consecutive non-reducing iterations before stagnation recovery\n fires (default: 3).\ninitial_trust_region_radius, max_trust_region_radius : float, optional\n Trust-region radius bounds (default: 1.0, 1e10).\nstep_accept_threshold : float, optional\n Minimum ρ for a step to be accepted (default: 1e-4).\ntrust_region_shrink_rho, trust_region_grow_rho : float, optional\n ρ thresholds for shrinking / growing the trust region\n (default: 0.25, 0.75).\ntrust_region_shrink_scale, trust_region_grow_scale : float, optional\n Multipliers applied to δ on shrink / grow (default: 0.25, 2.0).\nlog_c_clamp : float, optional\n Upper bound on ``log_q + Aᵀλ`` before exp() (default: 700.0).\nlog_q_clamp : float or None, optional\n Optional upper bound on ``log_q = -ΔG/RT`` applied at\n construction time (default: None).\nobjective : str, optional\n Trust-region objective surface: ``"linear"`` (default) minimizes\n the convex Dirks dual ``f(λ)`` directly; ``"log"`` minimizes\n ``g(λ) = ln f(λ)``. The log path can converge in many fewer\n iterations on stiff systems (very strong binding, asymmetric\n ``c⁰``) but is non-convex; equiconc handles the resulting\n indefinite Hessians via on-the-fly modified-Cholesky\n regularization. The mass-conservation convergence test is\n identical for both. Default: ``"linear"``.' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

`module = 'equiconc'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

`gradient_abs_tol` `property` ¶

`gradient_rel_tol` `property` ¶

`initial_trust_region_radius` `property` ¶

`log_c_clamp` `property` ¶

`log_q_clamp` `property` ¶

`max_iterations` `property` ¶

`max_trust_region_radius` `property` ¶

`objective` `property` ¶

`relaxed_gradient_abs_tol` `property` ¶

`relaxed_gradient_rel_tol` `property` ¶

`stagnation_threshold` `property` ¶

`step_accept_threshold` `property` ¶

`trust_region_grow_rho` `property` ¶

`trust_region_grow_scale` `property` ¶

`trust_region_shrink_rho` `property` ¶

`trust_region_shrink_scale` `property` ¶

`new(*args, **kwargs)` `builtin` ¶

Create and return a new object. See help(type) for accurate signature.

`repr()` `method descriptor` ¶

Return repr(self).

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.

API Reference¶

System¶

System ¶

monomer(name, total_concentration) method descriptor ¶

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

equilibrium() method descriptor ¶

SolverOptions¶

SolverOptions ¶

__module__ = 'equiconc' class-attribute ¶

gradient_abs_tol property ¶

gradient_rel_tol property ¶

initial_trust_region_radius property ¶

log_c_clamp property ¶

log_q_clamp property ¶

max_iterations property ¶

max_trust_region_radius property ¶

objective property ¶

relaxed_gradient_abs_tol property ¶

relaxed_gradient_rel_tol property ¶

stagnation_threshold property ¶

step_accept_threshold property ¶

trust_region_grow_rho property ¶

trust_region_grow_scale property ¶

trust_region_shrink_rho property ¶

trust_region_shrink_scale property ¶

__new__(*args, **kwargs) builtin ¶

__repr__() method descriptor ¶

Equilibrium¶

Equilibrium ¶

monomer_names property ¶

complex_names property ¶

free_monomer_concentrations property ¶

complex_concentrations property ¶

converged_fully property ¶

concentration(name) method descriptor ¶

to_dict() method descriptor ¶

keys() method descriptor ¶

values() method descriptor ¶

items() method descriptor ¶

`System` ¶

`monomer(name, total_concentration)` `method descriptor` ¶

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

`equilibrium()` `method descriptor` ¶

`SolverOptions` ¶

`module = 'equiconc'` `class-attribute` ¶

`gradient_abs_tol` `property` ¶

`gradient_rel_tol` `property` ¶

`initial_trust_region_radius` `property` ¶

`log_c_clamp` `property` ¶

`log_q_clamp` `property` ¶

`max_iterations` `property` ¶

`max_trust_region_radius` `property` ¶

`objective` `property` ¶

`relaxed_gradient_abs_tol` `property` ¶

`relaxed_gradient_rel_tol` `property` ¶

`stagnation_threshold` `property` ¶

`step_accept_threshold` `property` ¶

`trust_region_grow_rho` `property` ¶

`trust_region_grow_scale` `property` ¶

`trust_region_shrink_rho` `property` ¶

`trust_region_shrink_scale` `property` ¶

`new(*args, **kwargs)` `builtin` ¶

`repr()` `method descriptor` ¶

`Equilibrium` ¶

`monomer_names` `property` ¶

`complex_names` `property` ¶

`free_monomer_concentrations` `property` ¶

`complex_concentrations` `property` ¶

`converged_fully` `property` ¶

`concentration(name)` `method descriptor` ¶

`to_dict()` `method descriptor` ¶

`keys()` `method descriptor` ¶

`values()` `method descriptor` ¶

`items()` `method descriptor` ¶