Skip to content

pbpk equilibration

The drug-free equilibration of a condition: equilibrated_simulation, which PBPKSimulationExperiment.equilibrated calls with the file of its loaded model and the groups of a sensitivity analysis use outside an experiment, drug_free_zeros (the species of the drugs which start exactly at 0), accumulating_states and growing_states, see Impairment. flat_model is what the equilibration and the validity of the kidney outflow read from a flat model file, parsed and compiled once per process.

The drug-free equilibration of a condition of a model of the library.

equilibrated_simulation equilibrates a simulation of a model file, the equilibration of PBPKSimulationExperiment.equilibrated (pkpdsim.pbpk.experiment, on the file of its loaded model) and of the groups of a sensitivity analysis: the presimulation of sbmlsim to the steady state of the condition, the doses moved to the start, the sinks, the readouts of the intestine which nothing drains and the resets set back, the species of the drugs set to exactly 0 (drug_free_zeros) and the states which grow without a steady state refused (accumulating_states, growing_states). A model file is parsed once per process (pkpdsim.pbpk.flat_model, by its path and modification time, shared with the validity of the kidney outflow); the docs are the section "Equilibration of a condition" of the impairment page.

The module imports sbmlsim; pkpdsim.pbpk exports its names lazily.

Equilibration dataclass 

Equilibration(
    resets=(lambda: MappingProxyType({}))(),
    absolute_tolerance=EQUILIBRATION_TOLERANCES[0],
    relative_tolerance=EQUILIBRATION_TOLERANCES[1],
    max_time=EQUILIBRATION_TOLERANCES[2],
)

The drug-free equilibration of the scans of a group of a sensitivity analysis.

The function of a pkpdsim.sensitivity.SensitivityGroup which prepares its scans (prepare): every point of a design starts from the drug-free steady state of its condition on the build of the group (equilibrated_simulation), which replaces a long pre-run from a negative start:

# not executed
SensitivityGroup(
    "renal_mild", "Mild renal impairment", simulation,
    prepare=Equilibration(resets={"FLUID__Aurine_h2o": 0.0}),
)

Attributes:

Name Type Description
resets Mapping[str, Quantity | float]

the values at the start of the further states which grow without a steady state, e.g. the urine of a PD component.
absolute_tolerance float

the absolute tolerance of the rates (per minute).
relative_tolerance float

the relative tolerance of the rates.
max_time float

the longest equilibration (minutes).

accumulating_states 

accumulating_states(sbml)

Get the states of a model which nothing drains: they only accumulate.

A state (the variable of a rate rule, a species which reactions change) which no rate reads, neither a rate rule nor a kinetic law, directly or through the assignment rules, and which no reaction consumes, e.g. the urine and the feces of the library or the urine of a PD component: with an inflow at the steady state of the rest of the model it grows without a steady state. A species which a rate reads is read with its compartment.

Parameters:

Name Type Description Default
sbml str

the SBML of the model, flat.

 required

Returns:

Type Description
tuple[str, ...]

The ids, sorted.

growing_states 

growing_states(model_path, condition, steady_state)

Get the states which grow without a steady state during an equilibration.

The accumulating states of the model (accumulating_states) whose value after the equilibration of the condition differs from their value at the initialization by more than the absolute tolerance (and 1e-9 of the value): an inflow at the steady state, which the presimulation reaches only relative to their growing amount (after about 1/relative_tolerance minutes), so their value at the start of the simulation is meaningless unless they are set back. They are found once per model file (and its modification time) and tolerances in a process, in the condition of the first equilibration: whether a state has no outflow is a property of the model.

Parameters:

Name Type Description Default
model_path Path

the flat SBML model.

 required
condition Mapping[str, Value]

the changes before the initialization.

 required
steady_state SteadyState

the presimulation.

 required

Returns:

Type Description
tuple[str, ...]

The ids of the growing states.

Raises:

Type Description
SteadyStateError

if the model reaches no steady state in the condition by max_time (sbmlsim).

drug_free_zeros 

drug_free_zeros(model_path, set_ids=())

Get the species which are exactly 0 at the drug-free steady state of a model.

The species of the substances without a baseline (Mr_<s> without baseline_<s>: the drugs and their metabolites, not an endogenous substance), which start at 0 and which no reaction feeds from a species with a start: a reaction moves a substance only from a species which holds some (a reactant, or a product of a reversible reaction), a reaction without reactants (a source) feeds its products unless it is a dose of the library (its rate reads PODOSE_<s>, IVDOSE_<s>, ..., which the equilibration moves to the start). The direction of a reaction is its SBML reversible flag: a CustomReaction whose rate law can run backwards (an exchange k*(A - B)) must be written reversible (A <-> B), else a species it feeds backwards from a started product is taken for 0; a source without reactants whose rate reads a dose id is taken for a dose. In exact arithmetic they stay 0 during a drug-free equilibration; a presimulation leaves a residue of the rounding in them (1.5e-29 mM in hctz), which PBPKSimulationExperiment.equilibrated sets back to 0.

Parameters:

Name Type Description Default
model_path Path

the flat SBML model.

 required
set_ids Iterable[str]

the ids which a simulation sets before the equilibration (its condition, the dimensions of a scan): a species among them holds what it is set to and feeds what it reaches; a concentration [sid] is the species sid.

 ()

Returns:

Type Description
tuple[str, ...]

The ids, sorted.

equilibrated_simulation 

equilibrated_simulation(
    simulation: Simulation,
    model_path: Path,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Simulation

equilibrated_simulation(
    simulation: Scan,
    model_path: Path,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Scan

equilibrated_simulation(
    simulation: Simulation | Scan,
    model_path: Path,
    *,
    resets: Mapping[str, Quantity | float] | None = None,
    absolute_tolerance: float = EQUILIBRATION_TOLERANCES[0],
    relative_tolerance: float = EQUILIBRATION_TOLERANCES[1],
    max_time: float = EQUILIBRATION_TOLERANCES[2],
) -> Simulation | Scan

equilibrated_simulation(
    simulation,
    model_path,
    *,
    resets=None,
    absolute_tolerance=EQUILIBRATION_TOLERANCES[0],
    relative_tolerance=EQUILIBRATION_TOLERANCES[1],
    max_time=EQUILIBRATION_TOLERANCES[2],
)

Get a simulation of a model file which starts from the drug-free steady state of its condition.

The equilibration of PBPKSimulationExperiment.equilibrated, which calls it with the file of its loaded model, and of a simulation outside an experiment, e.g. the groups of a sensitivity analysis (pkpdsim.sensitivity.SensitivityGroup(prepare=Equilibration(...))): the ids of the doses, the sinks, the readouts of the intestine and the deltas are read from the model file (the doses move to the start, the sinks, the readouts which nothing drains and resets are set back, the species of the drugs are exactly 0, a growing state without a reset is refused, every point of a scan equilibrates in its own condition), see PBPKSimulationExperiment.equilibrated. It replaces a long pre-run from a negative start, which leaves a slow state off its steady state.

Parameters:

Name Type Description Default
simulation Simulation | Scan

the simulation or the scan, in the condition.

 required
model_path Path

the flat SBML model the simulation runs.

 required
resets Mapping[str, Quantity | float] | None

the values at the start of the further states which grow without a steady state, e.g. the urine of a PD component; a species by its id (a concentration species is set as [sid]).

 None
absolute_tolerance float

the absolute tolerance of the rates of the equilibration (per minute).

 EQUILIBRATION_TOLERANCES[0]
relative_tolerance float

the relative tolerance of the rates.

 EQUILIBRATION_TOLERANCES[1]
max_time float

the longest equilibration (minutes).

 EQUILIBRATION_TOLERANCES[2]

Returns:

Type Description
Simulation | Scan

The equilibrated simulation or scan, a new object.

Raises:

Type Description
ValueError

as PBPKSimulationExperiment.equilibrated.

flat_model

What the library reads from a flat model file, parsed and compiled once.

The equilibration of a condition (pkpdsim.pbpk.equilibration) and the validity of the kidney outflow (pkpdsim.pbpk.kidney_validity) read the same built model: its species and parameters, the states which nothing drains, the reactions, the filtered substances and the ids the flows of the kidney depend on. flat_model parses the file once per process (by its path and modification time, so a file which is built again is read again) and gives all of it as a FlatModel; loaded_model compiles the model once (roadrunner at LLJIT O0, the fastest compilation, since its simulations only reach a steady state or evaluate the initial assignments) with the selections of both, so a model with two builds compiles each build once for both checks. math_names is the one walker of the names a formula of the model reads.

The module imports sbmlsim and libsbml; it is internal to the library.

FilteredSubstance dataclass 

FilteredSubstance(sid, kinetic, threshold)

A filtered substance of a flat model.

Attributes:

Name Type Description
sid str

the substance.
kinetic bool

its erythrocytes are kinetic: the plasma carries it, else BP does, which is 1 - HCT without erythrocytes.
threshold bool

it has a threshold reabsorption (reab_threshold_<s>), no f_reabsorbed_<s>.

FlatModel dataclass 

FlatModel(
    species,
    parameters,
    accumulating,
    candidates,
    started,
    concentrations,
    reactions,
    filtered,
    water,
    quantities,
    inputs,
)

What the library reads from a flat model file.

Attributes:

Name Type Description
species frozenset[str]

the ids of the species.
parameters frozenset[str]

the ids of the parameters.
accumulating tuple[str, ...]

the states which nothing drains (accumulating).
candidates frozenset[str]

the species of the substances without a baseline which start at 0 (no initial assignment, no rule, not constant), see pkpdsim.pbpk.equilibration.drug_free_zeros.
started frozenset[str]

the species with a start: an initial value other than 0, an initial assignment or a rule.
concentrations frozenset[str]

the species whose id means their concentration (hasOnlySubstanceUnits false): a change sets them as [sid].
reactions tuple[tuple[frozenset[str], frozenset[str], bool, frozenset[str]], ...]

(reactants, products, reversible, the names its rate reads) of every reaction.
filtered tuple[FilteredSubstance, ...]

the filtered substances of the kidney.
water bool

the model has the GFR, the flow of the kidney and the hematocrit, whose filtered plasma water is bounded.
quantities tuple[str, ...]

the ids of the flows of the validity of the kidney outflow and GFR_base which the model has.
inputs frozenset[str]

the ids which the quantities depend on, through initial assignments and assignment rules (themselves included): the changes of an individual.

selections property 

selections

The selections of the loaded model: the time, the states and the flows.

math_names 

math_names(ast)

Get the names a formula of a model reads.

Parameters:

Name Type Description Default
ast ASTNode | None

the formula, None for none.

 required

Returns:

Type Description
set[str]

The names of the formula (AST_NAME), not the time.

accumulating 

accumulating(model)

Get the states of a parsed model which nothing drains, sorted.

See pkpdsim.pbpk.equilibration.accumulating_states.

flat_model 

flat_model(model_path)

Get what the library reads from a flat model file, parsed once per process.

Parameters:

Name Type Description Default
model_path Path

the flat SBML model.

 required

Returns:

Type Description
FlatModel

The parsed model, cached by the path and the modification time.

loaded_model 

loaded_model(model_path)

Get a flat model file compiled once per process, at O0.

The selections are those of the equilibration and of the validity of the kidney outflow (FlatModel.selections); the four models used last stay loaded.

Parameters:

Name Type Description Default
model_path Path

the flat SBML model.

 required

Returns:

Type Description
RoadrunnerSBMLModel

The loaded model, cached by the path and the modification time.