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.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.

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

constraints¶: Get list of model constraints.

data¶: Get the experimental data object.

data_length¶: Get the length of the data array.

is_feasible¶: Check if model parameters satisfy all constraints.

name¶: Get the model name.

num_of_variables¶: Get the size of the model domain.

parameters¶: Get list of model parameters.

residuals¶: Get the residuals array.

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.

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

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.

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.

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

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.

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

constrain(val) → None¶: Add constraint.

constraints¶

is_feasible¶

name¶

parameters¶

sum_constraint_violations¶

unconstrain(val) → None¶: Remove constraint.

unconstrain_all() → None¶: Remove all constraints.