Model and modelstack

The escape.core.model module provides methods to create models objects.

Classes

model_obj

Container for a kernel 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.

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: - “none”: No scaling - “log”: Logarithmic scaling - “sqrt”: Square root scaling - “q2”: Q^2 scaling - “q4”: Q^4 scaling - “logq”: Logarithmic Q scaling - “log_q2”: Logarithmic Q^2 scaling - “log_q4”: Logarithmic Q^4 scaling

escape.core.model.model(name: str, obj: Union[kernel_obj, functor_obj], data: data_obj, weight_type: str = 'data', residuals_scale: str = 'none', cost: Optional[cost_obj] = None) → model_obj

Create a new model object.

Args:

name: Model name obj: Kernel or 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’, ‘q2’, ‘q4’, ‘log_q2’, ‘log_q4’)

Returns:

New model object

Raises:

TypeError: If obj is not a kernel_obj or functor_obj

escape.core.model.cost(name: str, weight_type: str = 'data', scaling: str = 'none') → cost_obj

Create a new cost function object.

Args:

name: Cost function name weight_type: Weight type for residuals (‘none’ or ‘data’) scaling: Scaling type (‘none’, ‘log’, ‘sqrt’, ‘q2’, ‘q4’, ‘logq’, ‘logq2’, ‘logq4’)

Returns:

New cost function object

Raises:

ValueError: If scaling type is not supported

escape.core.model.modelstack(name: str, model: Optional[Union[model_obj, List[model_obj]]] = None) → modelstack_obj

Create a new model stack object.

Args:

name: Stack name model: Single model or list of models to add

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_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: Optional[Any] = 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: Optional[Any] = None, config: Optional[Any] = 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 data 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.

namestr

Name of the cost function

parametersList[parameter_obj]

List of parameters

constraintsList[bool_parameter_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.