pymixef.pharmacometrics.dsl module¶

Typed, introspectable declarations for pharmacometric models.

This module provides a small Python-native declaration language. Arithmetic builds immutable expression trees; it is not evaluated with eval and it does not embed optimizer-specific control statements.

The model() decorator intentionally does not claim that arbitrary Python functions are safe to inspect. A decorated function is executed lazily when it is compiled, just like any other Python function. Projects that must inspect untrusted model text should deserialize a validated model IR instead of importing and executing that text. Once compiled, the returned CompiledModel is data-only and fully introspectable.

class pymixef.pharmacometrics.dsl.CompiledModel(name, parameters=(), etas=(), states=(), symbols=(), doses=(), equations=(), observations=(), schema_version='1.0', authoring_mode='executed-python-declarations')[source]¶

Bases: object

Data-only pharmacometric model declaration.

Parameters:

name (str)
parameters (tuple[Param, ...])
etas (tuple[Eta, ...])
states (tuple[State, ...])
symbols (tuple[Symbol, ...])
doses (tuple[Dose, ...])
equations (tuple[DifferentialEquation, ...])
observations (tuple[Observation, ...])
schema_version (str)
authoring_mode (str)

name: str¶

parameters: tuple[Param, ...]¶

etas: tuple[Eta, ...]¶

states: tuple[State, ...]¶

symbols: tuple[Symbol, ...]¶

doses: tuple[Dose, ...]¶

equations: tuple[DifferentialEquation, ...]¶

observations: tuple[Observation, ...]¶

schema_version: str¶

authoring_mode: str¶

to_ir()[source]¶

Compile this declaration into the common, versioned ModelIR.

Only expression and residual-error operations with defined semantic mappings are accepted. Custom operations fail here rather than being reduced to an opaque string that a backend could misinterpret.

Return type:: ModelIR

validate(*, raise_on_error=False)[source]¶

Validate names, equation coverage, mappings, and engine readiness.

Parameters:: raise_on_error (bool)
Return type:: ModelValidation

explain()[source]¶

Print the implied equations, transforms, event mappings, and units.

Return type:: str

to_dict()[source]¶

Serialize the complete, optimizer-independent declaration.

Return type:: dict[str, Any]

exception pymixef.pharmacometrics.dsl.DSLValidationError[source]¶

Bases: ValueError

Raised when declarations do not form a valid pharmacometric model.

code = 'DSL-INVALID-001'¶

class pymixef.pharmacometrics.dsl.DifferentialEquation(state, expression)[source]¶

Bases: object

One first-order ODE declaration.

Parameters:

state (State)
expression (Expr)

state: State¶

expression: Expr¶

to_dict()[source]¶

Return type:: dict[str, Any]

format()[source]¶

Return type:: str

class pymixef.pharmacometrics.dsl.Dose(state, amount='AMT', rate='RATE', duration='DUR', compartment='CMT', lag=None, bioavailability=None, route='iv')[source]¶

Bases: object

Mapping from canonical event fields to a model state.

Parameters:

state (State)
amount (str)
rate (str | None)
duration (str | None)
compartment (str)
lag (str | float | None)
bioavailability (str | float | None)
route (str)

state: State¶

amount: str¶

rate: str | None¶

duration: str | None¶

compartment: str¶

lag: str | float | None¶

bioavailability: str | float | None¶

route: str¶

classmethod into(state, *, amount='AMT', rate='RATE', duration='DUR', compartment='CMT', lag=None, bioavailability=None, route='iv')[source]¶

Declare how dose records enter a state.

Parameters:

state (State)
amount (str)
rate (str | None)
duration (str | None)
compartment (str)
lag (str | float | None)
bioavailability (str | float | None)
route (str)

Return type:

Dose

to_dict()[source]¶

Return type:: dict[str, Any]

class pymixef.pharmacometrics.dsl.Eta(name, block, covariance='diagonal', level='subject')[source]¶

Bases: _Symbolic

A named random effect and its covariance-block declaration.

Parameters:

name (str)
block (str)
covariance (Literal['correlated', 'diagonal'])
level (str)

name: str¶

block: str¶

covariance: Literal['correlated', 'diagonal']¶

level: str¶

classmethod correlated(*names, block=None, level='subject')[source]¶

Parameters:

names (str)
block (str | None)
level (str)

Return type:

tuple[Eta, …]

classmethod independent(*names, block=None, level='subject')[source]¶

Parameters:

names (str)
block (str | None)
level (str)

Return type:

tuple[Eta, …]

as_expr()[source]¶

Return type:: Expr

to_dict()[source]¶

Return type:: dict[str, str]

class pymixef.pharmacometrics.dsl.Expr(operation, arguments=(), value=None, metadata=<factory>)[source]¶

Bases: object

An immutable symbolic expression node.

Parameters:

operation (str)
arguments (tuple[Expr, ...])
value (float | str | None)
metadata (Mapping[str, Any])

operation: str¶

arguments: tuple[Expr, ...]¶

value: float | str | None¶

metadata: Mapping[str, Any]¶

to_dict()[source]¶

Serialize the expression tree.

Return type:: dict[str, Any]

format()[source]¶

Return a deterministic, human-readable mathematical expression.

Return type:: str

evaluate(values)[source]¶

Evaluate using an explicit symbol table.

This method traverses the already-built expression tree. It never evaluates source code. Missing names raise KeyError.

Parameters:: values (Mapping[str, float])
Return type:: float

class pymixef.pharmacometrics.dsl.ModelDefinition(function, *, name=None)[source]¶

Bases: object

Lazy wrapper produced by model().

Calling or compiling it executes the original Python declaration function once per call in an isolated context. This behavior is explicit in CompiledModel.authoring_mode.

Parameters:

function (Callable[..., Any])
name (str | None)

compile(*args, **kwargs)[source]¶

Parameters:

args (Any)
kwargs (Any)

Return type:

CompiledModel

validate(*args, **kwargs)[source]¶

Parameters:

args (Any)
kwargs (Any)

Return type:

ModelValidation

explain(*args, **kwargs)[source]¶

Parameters:

args (Any)
kwargs (Any)

Return type:

str

to_dict(*args, **kwargs)[source]¶

Parameters:

args (Any)
kwargs (Any)

Return type:

dict[str, Any]

to_ir(*args, **kwargs)[source]¶

Compile the declaration into the common versioned model IR.

Parameters:

args (Any)
kwargs (Any)

Return type:

ModelIR

property declaration_signature: str¶

class pymixef.pharmacometrics.dsl.ModelValidation(valid, messages, dimensions, estimator_compatibility)[source]¶

Bases: object

Dry-run validation report for a compiled model.

Parameters:

valid (bool)
messages (tuple[ValidationMessage, ...])
dimensions (Mapping[str, int])
estimator_compatibility (Mapping[str, bool])

valid: bool¶

messages: tuple[ValidationMessage, ...]¶

dimensions: Mapping[str, int]¶

estimator_compatibility: Mapping[str, bool]¶

to_dict()[source]¶

Return type:: dict[str, Any]

raise_for_errors()[source]¶

Return type:: None

class pymixef.pharmacometrics.dsl.Observation(endpoint, mean, error, censored_below=None, censored_above=None, metadata=<factory>)[source]¶

Bases: object

An endpoint, prediction expression, and residual-error declaration.

Parameters:

endpoint (str)
mean (Expr)
error (Any)
censored_below (str | float | None)
censored_above (str | float | None)
metadata (Mapping[str, Any])

endpoint: str¶

mean: Expr¶

error: Any¶

censored_below: str | float | None¶

censored_above: str | float | None¶

metadata: Mapping[str, Any]¶

to_dict()[source]¶

Return type:: dict[str, Any]

class pymixef.pharmacometrics.dsl.Param(name, init, constraint='real', lower=None, upper=None, unit=None, description=None)[source]¶

Bases: _Symbolic

A population parameter with an explicit natural-scale constraint.

Parameters:

name (str)
init (float)
constraint (Literal['real', 'positive', 'bounded'])
lower (float | None)
upper (float | None)
unit (str | None)
description (str | None)

name: str¶

init: float¶

constraint: Literal['real', 'positive', 'bounded']¶

lower: float | None¶

upper: float | None¶

unit: str | None¶

description: str | None¶

classmethod real(name, *, init=0.0, unit=None, description=None)[source]¶

Parameters:

name (str)
init (float)
unit (str | None)
description (str | None)

Return type:

Param

classmethod positive(name, *, init, unit=None, description=None)[source]¶

Parameters:

name (str)
init (float)
unit (str | None)
description (str | None)

Return type:

Param

classmethod bounded(name, *, init, lower, upper, unit=None, description=None)[source]¶

Parameters:

name (str)
init (float)
lower (float)
upper (float)
unit (str | None)
description (str | None)

Return type:

Param

as_expr()[source]¶

Return type:: Expr

to_dict()[source]¶

Return type:: dict[str, Any]

class pymixef.pharmacometrics.dsl.State(name, unit=None, initial=0.0)[source]¶

Bases: _Symbolic

An ODE state/compartment declaration.

Parameters:

name (str)
unit (str | None)
initial (float)

name: str¶

unit: str | None¶

initial: float¶

as_expr()[source]¶

Return type:: Expr

derivative(expression)[source]¶

Declare d(state)/dt inside the active model.

Parameters:: expression (Expr | _Symbolic | int | float | number)
Return type:: DifferentialEquation

to_dict()[source]¶

Return type:: dict[str, Any]

class pymixef.pharmacometrics.dsl.Symbol(name, role='covariate', unit=None, reference=None)[source]¶

Bases: _Symbolic

A named covariate or external model input.

Parameters:

name (str)
role (str)
unit (str | None)
reference (float | str | None)

name: str¶

role: str¶

unit: str | None¶

reference: float | str | None¶

as_expr()[source]¶

Return type:: Expr

to_dict()[source]¶

Return type:: dict[str, Any]

class pymixef.pharmacometrics.dsl.ValidationMessage(code, severity, message)[source]¶

Bases: object

One coded severity and message emitted by dry-run model validation.

Parameters:

code (str)
severity (Literal['error', 'warning', 'info'])
message (str)

code: str¶

severity: Literal['error', 'warning', 'info']¶

message: str¶

to_dict()[source]¶

Return type:: dict[str, str]

pymixef.pharmacometrics.dsl.as_expr(value)[source]¶

Convert declarations and numeric constants to an expression node.

Parameters:: value (Expr | _Symbolic | int | float | number)
Return type:: Expr

pymixef.pharmacometrics.dsl.compiled_model(name, *, parameters=(), etas=(), states=(), symbols=(), doses=(), equations=(), observations=(), validate=True)[source]¶

Build a data-only model directly, without executing a declaration function.

Parameters:

name (str)
parameters (Sequence[Param])
etas (Sequence[Eta])
states (Sequence[State])
symbols (Sequence[Symbol])
doses (Sequence[Dose])
equations (Sequence[DifferentialEquation])
observations (Sequence[Observation])
validate (bool)

Return type:

CompiledModel

pymixef.pharmacometrics.dsl.covariate(name, *, unit=None, reference=None)[source]¶

Declare a covariate symbol.

Parameters:

name (str)
unit (str | None)
reference (float | str | None)

Return type:

Symbol

pymixef.pharmacometrics.dsl.d(state, expression)[source]¶

Short alias for derivative().

Python does not permit the illustrative syntax d(state) = expression; PyMixEF therefore uses d(state, expression) or state.derivative(expression).

Parameters:

state (State)
expression (Expr | _Symbolic | int | float | number)

Return type:

DifferentialEquation

pymixef.pharmacometrics.dsl.derivative(state, expression)[source]¶

Declare a state derivative in the active model.

Parameters:

state (State)
expression (Expr | _Symbolic | int | float | number)

Return type:

DifferentialEquation

pymixef.pharmacometrics.dsl.exp(value)[source]¶

Build a symbolic exponential expression without evaluating value.

Parameters:: value (Expr | _Symbolic | int | float | number)
Return type:: Expr

pymixef.pharmacometrics.dsl.log(value)[source]¶

Build a symbolic natural-log expression without checking its domain.

Parameters:: value (Expr | _Symbolic | int | float | number)
Return type:: Expr

pymixef.pharmacometrics.dsl.log1p(value)[source]¶

Build a symbolic log(1 + value) expression without evaluating it.

Parameters:: value (Expr | _Symbolic | int | float | number)
Return type:: Expr

pymixef.pharmacometrics.dsl.model(function: Callable[[P], R], /) → ModelDefinition[source]¶
pymixef.pharmacometrics.dsl.model(*, name: str | None = None) → Callable[[Callable[[P], R]], ModelDefinition]: Decorate a Python function as a lazy model declaration.

pymixef.pharmacometrics.dsl.observe(endpoint, *, mean, error, censored_below=None, censored_above=None, metadata=None)[source]¶

Declare an observation endpoint in the active model.

Parameters:

endpoint (str)
mean (Expr | _Symbolic | int | float | number)
error (Any)
censored_below (str | float | None)
censored_above (str | float | None)
metadata (Mapping[str, Any] | None)

Return type:

Observation

pymixef.pharmacometrics.dsl.sqrt(value)[source]¶

Build a symbolic square-root expression without checking its domain.

Parameters:: value (Expr | _Symbolic | int | float | number)
Return type:: Expr

pymixef.pharmacometrics.dsl.symbol(name, *, role='covariate', unit=None, reference=None)[source]¶

Declare a typed covariate or other external model input.

Parameters:

name (str)
role (str)
unit (str | None)
reference (float | str | None)

Return type:

Symbol