TemplateIntegrator

For supervised classification workflows, templates are managed by the TemplateIntegrator class.

See the Predictors User Guide for usage examples.

pybasin.template_integrator.TemplateIntegrator

Integrates template initial conditions and extracts training data for supervised classifiers.

Handles the ODE integration of known attractor templates and feature extraction.

Attributes:

Name	Type	Description
template_y0		Template initial conditions.
labels		Ground truth labels for each template.
ode_params		ODE parameters for template integration (may differ from main study).
solver		Optional dedicated solver for template integration.
solution	Solution | None	Populated after :meth:integrate is called.

Attributes

has_dedicated_solver property

has_dedicated_solver: bool

Check if a dedicated solver was provided for template integration.

Functions

__init__

__init__(
    template_y0: list[list[float]],
    labels: list[str],
    ode_params: Mapping[str, Any],
    solver: SolverProtocol | None = None,
)

Initialize the template integrator.

Parameters:

Name	Type	Description	Default
template_y0	list[list[float]]	Template initial conditions as a list of lists (e.g., [[0.5, 0.0], [2.7, 0.0]]). Will be converted to tensor with appropriate device during integration.	required
labels	list[str]	Ground truth labels for template conditions.	required
ode_params	Mapping[str, Any]	ODE parameters mapping (dict or TypedDict with numeric values).	required
solver	SolverProtocol | None	Optional dedicated solver for template integration. If provided, this solver will be used instead of the main solver (useful for CPU-based template integration when templates are few).	None

integrate

integrate(
    solver: SolverProtocol | None,
    ode_system: ODESystemProtocol,
) -> Solution

Integrate ODE for template initial conditions.

If no dedicated solver was provided at init, automatically creates a CPU variant of the passed solver for better performance with small batch sizes.

Parameters:

Name	Type	Description	Default
solver	SolverProtocol | None	Fallback solver if none was provided at init. Can be None if a solver was provided during initialization.	required
ode_system	ODESystemProtocol	ODE system to integrate.	required

Raises:

Type	Description
ValueError	If no solver is available.

get_training_data

get_training_data(
    feature_extractor: FeatureExtractor,
    feature_selector: FeatureSelectorProtocol | None = None,
) -> tuple[np.ndarray, list[str]]

Extract features from integrated templates and return training data.

Must call :meth:integrate first to populate self.solution.

Parameters:

Name	Type	Description	Default
feature_extractor	FeatureExtractor	Feature extractor (already fitted on main data).	required
feature_selector	FeatureSelectorProtocol | None	Optional feature selector (already fitted on main data). If provided, applies the same filtering to template features.	None

Returns:

Type	Description
tuple[ndarray, list[str]]	Tuple of (X_train, y_labels) ready for classifier.fit().

Raises:

Type	Description
RuntimeError	If :meth:integrate was not called first.
ValueError	If filtering removes all template features.