API reference#

Model and analyses#

class symident.Model(odes=None, observables=None, *, reactions=None, totals=None, trafo=None, conditions=None, events=None, inputs=(), fixed=(), parameters=(), regimes=None)[source]#

An ODE model with observables, conditions and events.

Parameters:

odesdict, optional: Right-hand sides, state name to expression (^ or ** for powers), with switches such as piecewise() and comparisons allowed (see the user guide). Derived from reactions when omitted.
observablesdict or list of dict: Observables, name to expression; a list gives one dict per condition.
reactionsdict, optional: Reaction network with keys species, stoichiometry (reactions by species) and rates. Needed for reduce_cq and the zero-state analysis under equilibrate.
totalsdict, optional: Conserved totals, name to expression; computed from reactions when omitted.
trafodict or list of dict, optional: Parameter transformation; an entry named like a state is its initial value.
conditionspandas.DataFrame or dict, optional: One row per condition; a numeric cell fixes a symbol, a string renames it. As a dict: {"rows": [...], "cols": {name: [values]}}.
eventslist of dict, optional: Events with keys var, time, value and method (replace, add or multiply); root in place of time resets var each time the root expression changes sign.
inputssequence of str: Input states, zero at rest.
fixedsequence of str: Known symbols.
parameterssequence of str: Additional symbols treated as parameters.
regimeslist or dict, optional: The regimes an experiment visits, for a model with switches: each entry is a comparison or a list of comparisons that selects the regimes on those sides, the first entry the regime at the start; a dict gives one list per condition name. Without it every regime counts. See the user guide.

symident.detect(model, *, scalings_only=False, equilibrate=False, reduce_cq=False, free_initial=None, reconstruct=False, positive=True, verify=True, gauge=False, cores=1, control=None, engine='modular', trace=False)[source]#

Structural non-identifiabilities of a model.

Parameters:

modelModel
scalings_onlybool: Only the scaling symmetries, from an exact integer kernel.
equilibratebool: Start at a steady state with the inputs at zero.
reduce_cqbool: Report moiety freedoms on conserved totals instead of single species.
free_initialsequence of str, optional: States that hold the free resting value of their moiety (equilibrate without reduce_cq).
reconstructbool: Return general directions as exact rational functions.
positivebool or sequence of str: Coordinates known to be positive.
verifybool: Check the rank where the Lie order is not certified.
gaugebool, None or sequence of str: False reconstructs every direction; None fixes one coordinate per scaling, chosen to keep the general directions narrow; a sequence ranks the coordinates to fix (* as wildcard).
coresint: Threads and worker processes.
controldict, optional: Settings from reconst_control().
enginestr: "modular" (finite fields) or "symbolic" (sympy, small models).
tracebool or str: Print stage timings; "full" adds the Lie-order diagnostics.

Returns:

Symmetries

symident.reduce(result, *, fixed=None, positive=True, d_poly=3, d_darboux=2, d_exp=2, separable=True, zero_limits=False, timeout=600, alternatives=False, verbose=False)[source]#

Reparametrisation that removes the directions of a detection result.

A scaling fixes one coordinate; a general direction is replaced by its invariants, each of which becomes a new parameter q_<k>.

Parameters:

resultSymmetries
fixedsequence of str, optional: Coordinates with known values; defaults to the gauge of the result.
positivebool or sequence of str: Coordinates known to be positive.
d_poly, d_darboux, d_expint: Degree bounds of polynomial and rational invariants, Darboux polynomials and exponential-factor numerators.
separablebool: Solve separable blocks by quadratures.
zero_limitsbool: Report which coordinates each block can drive to zero.
timeoutfloat: Time limit of the chart search per block in seconds.
alternativesbool: Build the charts of every admissible choice of pinned coordinates, not only when the first one holds a root that does not simplify.

Returns:

Reduction

Results#

class symident.Symmetries(raw, model=None)[source]#

Result of detect().

Attributes:

identifiablebool or None: Whether the model is structurally locally identifiable.
rank, dimint: Rank of the observability matrix and number of coordinates.
symmetrieslist of Symmetry: The non-identifiable directions; a direction is the generator \(X = \sum_i \eta_i \, \partial_{z_i}\).
infodict: Lie order, certification, rank proof, coordinates and settings.
gaugelist of str or None: The coordinates fixed by a gauged detection.

summary(verbose=False)[source]#: The computation report and the result.

reduce(**kwargs)[source]#: Shortcut for reduce().

to_dict()[source]#: The raw result as nested dicts and lists.

class symident.Symmetry[source]#

One non-identifiable direction, a dict whose entries are also attributes.

Attributes:

typestr: "scaling" or "general".
supportlist of str: Coordinates the direction moves.
explicitbool: Whether the generator is known in closed form.
generatordict or None: Component \(\eta_i\) per coordinate as a string; None when not reconstructed.
weightsdict or None: Integer weights \(w_i\) of a scaling, \(\eta_i = w_i z_i\).
degreeint or None: Total degree of the components.
certifiedbool: Whether the direction is proven exactly rather than found by sampling.
routestr or None: How a closed form was obtained, e.g. "static subsystem".
reasonstr or None: Why a direction has no closed form.
complete_generator, factordict or None, str or None: The generator times factor, a positive function that makes its flow exist for all times; None for very long components.
displaydict: Factored components of a general direction, where shorter.

sympy()[source]#: The generator components as sympy expressions.

class symident.Reduction(raw)[source]#

Result of reduce().

Attributes:

trafodict or None: Parameter transformation over all coordinates; None if nothing was reduced.
blockslist of dict: One entry per set of coupled directions: invariants, section, survivor_meaning (the invariant each new parameter q_<k> stands for), carrier_domain, coverage and status.
removed, remaininglist of str: Labels of the directions.
dependentlist of str: Labels of listed directions that depend on the others and need no reduction.
alternativeslist of dict: Other admissible charts, each with trafo, pins, removed, remaining and rational; the returned chart removes the most directions and prefers a rational trafo.
partiallist of str: Removed directions whose chart covers only part of the positive orthant: some positive coordinates have no positive preimage in the new parameters.

summary(verbose=False, detailed=False)[source]#: The verdict, the chart and one line per block. detailed explains each section.

to_dict()[source]#: The raw reduction as nested dicts and lists.

Settings and programs#

symident.reconst_control(relevance_cap=6, relevance_cap_dir=24, relevance_cap_sparse=30, degree_cap=4, sample_slack=5, probe_retries=8, laurent_deg_num=4, laurent_deg_den=2, laurent_cand_cap=200000, term_cap=60, general_deg_num=4, general_deg_den=3, gap_order_cap=8, minsupport_cand_cap=20000, perprime_cap=120, perprime_min_primes=3, homotopy=True, timeout=inf)[source]#

Saturation and closed-form reconstruction settings.

Parameters:

relevance_capint: Coordinates in one entry for the dense fit; wider entries use sparse interpolation.
relevance_cap_dirint: Coordinates in one direction; a wider one is reported by its support.
relevance_cap_sparseint: Coordinates in one entry for the sparse fit; a wider entry is reported by its support.
degree_capint: Total degree bound of the dense rational fit.
sample_slackint: Samples beyond the minimum of the fit.
probe_retriesint: Retries of the relevance probe when a perturbation changes the pivots.
laurent_deg_num, laurent_deg_denint: Numerator degree and monomial denominator degree of the sparse Laurent fit.
laurent_cand_capint: Candidate monomials of the Laurent and general sparse fits.
term_capint: Terms of a sparse entry.
general_deg_num, general_deg_denint: Numerator and denominator degree of the general sparse rational fit.
gap_order_capint: Order of the power series in the time between events.
minsupport_cand_capint: Column subsets searched for directions with small support.
perprime_capint: Samples per prime for the reconstruction under a steady state.
perprime_min_primesint: Primes with samples for a reconstruction under a steady state.
homotopybool: Whether directions still open under a steady state are fitted along parameter lines as a last route.
timeoutfloat: Time limit of the reconstruction in seconds; unfinished directions are reported by their support.

Returns:

dict

symident.install_msolve(dir=None, version='0.10.1', jobs=None, quiet=False, ask=None)[source]#

Build msolve from source into a per-user cache.

msolve solves the coupled resting-state systems of detect(..., equilibrate=True). It is built with static GMP, MPFR and FLINT; the build needs a C compiler, make, m4 and curl or wget, network access and a few minutes. Not available on Windows. symident finds the build without further settings.

Parameters:

dirstr, optional: Cache directory; defaults to cache_dir().
versionstr: msolve release.
jobsint, optional: Parallel make jobs; defaults to the available cores, at most 8.
quietbool: Suppress the build output.
askbool, optional: Ask before downloading; defaults to whether the session is interactive.

Returns:

str or None: Path of the msolve executable, None if the user declined.

symident.install.find_msolve()[source]#

The msolve to use and where it was found, (path, source), or (None, None).

Searched in order: SYMIDENT_MSOLVE, the builds of install_msolve() in the cache, then msolve on the PATH if it is a tested version. Each candidate must solve a test system.

symident.install.cache_dir()[source]#: The per-user cache of symident: SYMIDENT_CACHE, else the platform’s cache directory.

exception symident.sym.msolve.MsolveMissingError[source]#: Raised when the msolve executable is not available.

JSON interface#

JSON interface for host languages: specification in, result out.

symident.rjson.detect_json(spec, env=None, options=None)[source]#: Detection from a JSON specification; the result as JSON, warnings under warnings.

symident.rjson.reduce_json(obj, args, env=None, options=None)[source]#: Reduction of a detection result given as JSON; the reduction as JSON.