pystra.active_learning.analysis.ActiveLearning#

Use it: User guide · Worked example · Theory

class ActiveLearning(model, limit_state, *, options=None, surrogate='kriging', learning_function='u', n_initial=None, n_candidates=10000, n_estimation=None, estimator=None, max_iterations=200, learning_threshold=None, target_cov=None, stopping_criterion=None, surrogate_kwargs=None, rng=None)[source]#

Bases: AnalysisObject

Enrich a surrogate in independent normal coordinates, then estimate Pf.

Parameters:

  • model (StochasticModel)

  • limit_state (LimitState) – Standard PySTRA analysis inputs. Failure is g <= 0.

  • options (SimulationOptions | None) – Block size and transformation. Sample sizes and precision are this class’s own arguments, so n_samples, target_cov, sampling_std and bins are rejected.

  • surrogate (str | Surrogate) – ‘kriging’ (default), ‘pce’, ‘pc_kriging’, or an explicitly supplied fitted-model implementation. A supplied object is refitted in place by run().

  • learning_function (str | LearningFunction) – ‘u’ (default), ‘eff’, ‘fbr’, or a stateless selection policy. EFF assumes Gaussian predictive uncertainty. FBR requires bootstrap replicates; its default stopping policy is BootstrapBounds.

  • n_initial (int | None) – Initial LHS size: max(12, 2*n_variables), or max(30, 5*n_variables) for sparse PCE or estimator-driven enrichment. Dense OLS uses at least twice the largest total-degree basis size.

  • n_candidates (int) – Fixed MC pool size, or maximum size of each estimator-generated enrichment pool (10000). Subset sample size belongs to the estimator.

  • n_estimation (int | None) – Shortcut for the default MonteCarloEstimator population (100000). Cannot be combined with an explicit estimator.

  • estimator (ReliabilityEstimator | None) – Default MonteCarloEstimator(). Owns its sampling uncertainty. EnrichmentEstimator implementations also resample the enrichment pool after every fit and supply measure-correct probability bands.

  • max_iterations (int) – Maximum added true evaluations (200), excluding the initial design.

  • learning_threshold (float | None) – U minimum (2), or EFF maximum (1e-3, in limit-state units). Only valid for a named learning function.

  • target_cov (float | None) – Shortcut for the default LearningThreshold’s final sampling CoV (0.1). Cannot be combined with an explicit stopping criterion.

  • stopping_criterion (StoppingCriterion | None) – Default LearningThreshold(), or BootstrapBounds() for FBR. Explicit policies separate convergence from selection, for example AllCriteria with beta bounds/stability.

  • surrogate_kwargs (dict | None) – Constructor settings for a named surrogate.

  • rng (int | Generator | None) – Random source of the run-owned LHS, candidates, final population and named surrogate optimizer. A seed repeats them on every run; a generator advances its own state. Adaptive exploration reuses a separate seed after each fit; final estimation is independent of that stream.

Notes

Candidate points are evaluated at most once. Predictions are batched. Nonconvergence warns and returns an explicit unfinished result. Exceptions invalidate any prior result. A finite pool may miss disconnected failures; bootstrap spread can miss common polynomial bias. Validate the surrogate independently for the problem being assessed.

Methods

init_run

Initialize the model's isoprobabilistic transformation.

run

Run from fresh state and return an immutable convergence record.
run()[source]#

Run from fresh state and return an immutable convergence record.

Return type:

ActiveLearningResult

init_run()#

Initialize the model’s isoprobabilistic transformation.

Uses the explicit copula or calibrates the legacy Gaussian Nataf correlation. Must be called at the start of every run() method in subclasses.

Return type:

None