BasinStabilityEstimator

pybasin.basin_stability_estimator.BasinStabilityEstimator

Core class for basin stability analysis.

Configures the analysis with an ODE system, sampler, and solver, and provides methods to estimate basin stability and save results.

Attributes:

Name	Type	Description
result	StudyResult | None	The last computed StudyResult, or None if run() has not been called.
y0	Tensor | None	Initial conditions tensor.
solution	Solution | None	Solution instance containing trajectory and analysis results.

Attributes

result property

result: StudyResult | None

The last computed StudyResult, or None if run() has not been called.

Functions

__init__

__init__(
    ode_system: ODESystemProtocol,
    sampler: Sampler,
    n: int = 10000,
    solver: SolverProtocol | None = None,
    feature_extractor: FeatureExtractor | None = None,
    predictor: BaseEstimator | None = None,
    template_integrator: TemplateIntegrator | None = None,
    feature_selector: FeatureSelectorProtocol
    | None = UNSET,
    detect_unbounded: bool = True,
    compute_orbit_data: list[int] | bool = False,
    output_dir: str | Path | None = None,
)

Initialize the BasinStabilityEstimator.

Parameters:

Name	Type	Description	Default
n	int	Number of initial conditions (samples) to generate.	10000
ode_system	ODESystemProtocol	The ODE system model (ODESystem or JaxODESystem).	required
sampler	Sampler	The Sampler object to generate initial conditions.	required
solver	SolverProtocol | None	The Solver object to integrate the ODE system (Solver or JaxSolver). If None, automatically instantiates JaxSolver for JaxODESystem or TorchDiffEqSolver for ODESystem with t_span=(0, 1000), t_steps=1000, t_eval=(850, 1000) (saves only the steady-state window), and device from sampler.	None
feature_extractor	FeatureExtractor | None	The FeatureExtractor object to extract features from trajectories. If None, defaults to TorchFeatureExtractor with minimal+dynamical features.	None
predictor	BaseEstimator | None	Any sklearn-compatible estimator (classifier or clusterer). Classifiers (is_classifier(predictor) is True) require a template_integrator for supervised learning. Clusterers (is_clusterer(predictor) is True) work unsupervised. Regressors are rejected. If None, defaults to HDBSCANClusterer(auto_tune=True, assign_noise=True).	None
template_integrator	TemplateIntegrator | None	Template integrator for supervised classifiers. Required when predictor is a classifier. Holds template initial conditions, labels, and ODE params for training.	None
feature_selector	FeatureSelectorProtocol | None	Feature filtering sklearn transformer with get_support() method. Defaults to DefaultFeatureSelector(). Pass None to disable filtering. Accepts any sklearn transformer (VarianceThreshold, SelectKBest, etc.) or Pipeline.	UNSET
detect_unbounded	bool	Enable unboundedness detection before feature extraction (default: True). Only activates when solver has event_fn configured (e.g., JaxSolver with event_fn). When enabled, unbounded trajectories are separated and labeled as "unbounded" before feature extraction to prevent imputed Inf values from contaminating features.	True
compute_orbit_data	list[int] | bool	Enable orbit data computation for orbit diagram plotting: - False (default): Disabled. - True: Compute for all state dimensions. - list[int]: Compute for specific state indices (e.g., [0, 1]).	False
output_dir	str | Path | None	Directory path for saving results (JSON, Excel, plots), or None to disable.	None

Raises:

Type	Description
TypeError	If predictor is a regressor.
ValueError	If predictor is a classifier but no template_integrator is provided.

run

run(parallel_integration: bool = True) -> StudyResult

Estimate basin stability by: 1. Generating initial conditions using the sampler. 2. Integrating the ODE system for each sample (in parallel) to produce a Solution. 3. Extracting features from each Solution. 4. Clustering/classifying the feature space. 5. Computing the fraction of samples in each basin.

This method sets: - self.y0 - self.solution

Parameters:

Name	Type	Description	Default
parallel_integration	bool	If True and using a supervised classifier with template integrator, run main and template integration in parallel.	True

Returns:

Type	Description
StudyResult	A StudyResult with basin stability values, errors, labels, and orbit data.

run_parameter_study

run_parameter_study(
    study_params: StudyParams,
) -> list[StudyResult]

Run a batched parameter study with vectorized integration and feature extraction.

Parameters:

Name	Type	Description	Default
study_params	StudyParams	Parameter study specification.	required

Returns:

Type	Description
list[StudyResult]	List of StudyResult, one per parameter combination, in iteration order.

get_errors

get_errors() -> dict[str, ErrorInfo]

Compute absolute and relative errors for basin stability estimates.

The errors are based on Bernoulli experiment statistics:

• e_abs = sqrt(S_B(A) * (1 - S_B(A)) / N) — absolute standard error
• e_rel = 1 / sqrt(N * S_B(A)) — relative error

Returns:

Type	Description
dict[str, ErrorInfo]	Dictionary mapping each label to an ErrorInfo with e_abs and e_rel keys.

Raises:

Type	Description
ValueError	If run() has not been called yet.

save

save() -> None

Save the basin stability results to a JSON file.

Converts numpy arrays and Solution objects to standard Python types.

Raises:

Type	Description
ValueError	If run() has not been called yet.
ValueError	If output_dir is not defined.

save_to_excel

save_to_excel() -> None

Save the basin stability results to an Excel file.

Includes grid samples, labels, and bifurcation amplitudes.

Raises:

Type	Description
ValueError	If run() has not been called yet.
ValueError	If output_dir is not defined.
ValueError	If no solution data is available.

---

Supervised Classification

For supervised classification workflows, see the TemplateIntegrator API.