Model and modelstack#

The escape.core.model module provides methods to create model objects, aligned with the C++ factories in escape/core/model.h (model, modelstack, cost and scale-cost factories).

Classes#

model_obj: Container for a functor and corresponding experimental data. Responsible for calculating residuals and cost function used by optimizers for curve fitting.
modelstack_obj: Container for multiple models that need to be optimized together.
cost_obj: Cost function calculator that can be configured with different scaling options (matches C++ cost(), log_scale_cost(), sqrt_scale_cost(), q2/q4/logq variants).

Settings#

weight_typestr: Controls how weights are applied in cost calculation: - “none”: No weights used - “data”: Weights from data object used
residuals_scalestr: Controls how residuals are calculated (same as C++ model(…, residuals_scale)): - “none”: No scaling - “log”: Logarithmic scaling - “sqrt”: Square root scaling - “q2”: Q^2 scaling - “q4”: Q^4 scaling - “logq”: Logarithmic Q scaling - “logq2”: Logarithmic Q^2 scaling - “logq4”: Logarithmic Q^4 scaling

escape.core.model.model(obj: functor_obj, data: data_obj, weight_type: str = 'data', residuals_scale: str = 'none', cost: cost_obj | None = None, cost_weight: float = 1.0, normalize_cost: bool = False, name: str = 'Model', notes: str = '') → model_obj#

Create a new model object (escape::model with functor_t, data_t).

Args:: obj: Functor object for intensity calculations data: Experimental data for cost function calculation cost: Cost function object. If given, weight_type and residuals_scale are ignored. weight_type: Weight type for residuals (‘none’ or ‘data’) residuals_scale: Scale for residuals (‘none’, ‘log’, ‘sqrt’, ‘q2’, ‘q4’, ‘logq’, ‘logq2’, ‘logq4’) cost_weight: Cost weight (bounded to [0, 1]) normalize_cost: If True, normalize cost by initial cost (default False). name: Model name notes: Model notes
Returns:: New model object
Raises:: TypeError: If obj is not a functor_obj

escape.core.model.simulation_model(obj: functor_obj, data: data_obj | None = None, name: str = 'Simulation Model', notes: str = '') → model_obj#

Create an optional-data model.

With data, the model computes simulation, residuals, and cost like a regular fitting model. Without data, call it with explicit coordinates to populate simulation while leaving residuals empty.

escape.core.model.cost(weight_type: str = 'data', scaling: str = 'none', cost_weight: float = 1.0, normalize_cost: bool = False, name: str = 'Cost', notes: str = '') → cost_obj#

Create a new cost function object (escape::cost / log_scale_cost / etc.).

Args:: weight_type: Weight type for residuals (‘none’ or ‘data’); used for scaling ‘none’ and ‘log’ scaling: Scaling type (‘none’, ‘log’, ‘sqrt’, ‘q2’, ‘q4’, ‘logq’, ‘logq2’, ‘logq4’) cost_weight: Cost weight (bounded to [0, 1]) normalize_cost: If True, normalize cost by initial cost (default False). name: Cost function name notes: Cost function notes
Returns:: New cost function object
Raises:: ValueError: If scaling type is not supported

escape.core.model.modelstack(model: model_obj | List[model_obj] | None = None, name: str = 'Model Stack', notes: str = '') → modelstack_obj#

Create a new model stack object (escape::modelstack() then add models).

Args:: model: Single model or list of models to add name: Stack name notes: Stack notes
Returns:: New model stack object
Raises:: TypeError: If model is not a model_obj or list of model_obj

class escape.core.model.model_obj#

A model class that wraps a C++ model_t object.

This class provides an interface to the C++ model implementation, handling parameter optimization, data fitting, and constraint management.

bind_python_object(observer=None)#

cache_snapshot() → None#: Snapshot current simulation/residuals into cached arrays.

cached_residuals#: Get the cached residuals array (last snapshot).

cached_simulation#: Get the cached simulation array (last snapshot).

constrain(val) → None#: Add a constraint to the model.

constraints#: Get list of model constraints.

cost#: Get the model’s cost function.

data#: Get the experimental data object.

data_length#: Get the length of the data array.

functor#: Get the model’s functor.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

is_feasible#: Check if model parameters satisfy all constraints.

name#: Get the model name.

num_of_variables#: Get the size of the model domain.

on_state_changed()#

on_value_changed()#

parameters#: Get list of model parameters.

residuals#: Get the residuals array.

set_cost(cobj) → None#: Replace the model’s cost function.

set_functor(fobj) → None#: Replace the model’s functor.

settings#: Get list of model settings.

shake() → None#: Randomize model parameters within their bounds.

show(config: Any | None = None, **kwargs) → Any#: Show model object in a widget.

simulation#: Get the simulated data array.

sum_constraint_violations#: Get the sum of constraint violations.

unbind_python_object()#

unconstrain(val) → None#: Remove a constraint from the model.

unconstrain_all() → None#: Remove all constraints from the model.

class escape.core.model.modelstack_obj#

A container class for multiple models that wraps a C++ modelstack_t object.

This class manages a collection of models, allowing batch operations and shared constraints.

add(mdl) → None#

Add a model to the stack.

Args:: mdl: Model to add

bind_python_object(observer=None)#

cache_snapshots() → None#: Snapshot simulation/residuals for every model in the stack.

constrain(val) → None#: Add constraint to all models.

constraints#: Get combined list of constraints from all models.

data#: Get combined data object for all models.

data_length#: Get total length of data across all models.

erase(idx) → None#

Remove model at specified index.

Args:: idx: Index of model to remove

erase_all() → None#: Remove all models.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

is_feasible#: Check if all models satisfy their constraints.

model(idx) → model_obj#

Get model at specified index.

Args:: idx: Index of model to retrieve
Returns:: Model object at index

name#: Get name of model stack.

on_state_changed()#

on_value_changed()#

parameters#: Get combined list of parameters from all models.

set(idx, mdl) → None#

Set model at specified index.

Args:: idx: Index to set mdl: Model to set at index

settings#: Get combined list of settings from all models.

shake() → None#: Randomize parameters for all models.

show(model_configs: Any | None = None, config: Any | None = None, **kwargs) → Any#

Show model stack in a widget.

Args:

model_configs: Either a single ModelConfig applied to all models,: or a list of ModelConfig for each model

config: Optional layout config for the stack widget **kwargs: Additional keyword arguments passed to ModelStackLayout

Returns:

ModelStackLayout widget displaying the model stack

sum_constraint_violations#: Get the sum of constraint violations.

unbind_python_object()#

unconstrain(val) → None#: Remove constraint from all models.

unconstrain_all() → None#: Remove all constraints from all models.

class escape.core.model.cost_obj#

Cost function calculator with configurable scaling.

Attributes#

namestr: Name of the cost function
parametersList[parameter_obj]: List of parameters
constraintsList[constraint_obj]: List of constraints
is_feasiblebool: Whether the cost function is feasible

bind_python_object(observer=None)#

constrain(val) → None#: Add constraint.

constraints#

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

is_feasible#

name#

on_state_changed()#

on_value_changed()#

parameters#

scaling#: Return the scaling strategy identifier (e.g. ‘none’, ‘log’, ‘sqrt’).

settings#

sum_constraint_violations#

unbind_python_object()#

unconstrain(val) → None#: Remove constraint.

unconstrain_all() → None#: Remove all constraints.