carapace_core/analysis/
error.rs

1/// Real error enum, not sentinel integers. Carries the context an
2/// OpenSees-style `-1`..`-5` return code would otherwise leave to
3/// out-of-band documentation.
4#[derive(Debug, Clone, Copy, PartialEq)]
5pub enum AnalysisError {
6    FailedToConverge {
7        step: usize,
8    },
9    SingularSystem,
10    /// An `Integrator::DisplacementControl`'s controlled DOF is fixed (not
11    /// part of the free-DOF system), so there's no equation to control.
12    InvalidConstraint,
13    /// `modal_analysis` was asked for more modes than the model has free
14    /// DOFs (or zero modes) — there's no such Krylov subspace to build.
15    InvalidModeCount {
16        requested: usize,
17        free_dofs: usize,
18    },
19    /// A configuration value is out of range, nonfinite, or not supported
20    /// in combination with the rest of the analysis. `field` names the
21    /// option in its wire-format spelling (e.g. `"integrator.minRadius"`).
22    InvalidOption {
23        field: &'static str,
24    },
25    /// Arc-length continuation found an unfrozen `LoadSeries::Path` pattern
26    /// (its slope isn't valid across a load reversal or breakpoint).
27    UnsupportedLoadSeries,
28    /// Arc-length continuation's combined reference-load sensitivity is
29    /// zero on every free equation: there is no load to continue.
30    ZeroLoadSensitivity,
31    /// Arc-length continuation must start from equilibrium. `measure` is the
32    /// force-test measure at entry (`||r||` for `NormUnbalance`, the largest
33    /// scaled component for `Combined`).
34    InitialStateNotInEquilibrium {
35        measure: f64,
36    },
37    /// The first arc-length tangent is singular and no `seed` direction was
38    /// configured to orient it.
39    MissingSeedDirection,
40    /// Every arc-length attempt for this step failed and the radius can't
41    /// be reduced further (or the retry budget is spent). `last_failure`
42    /// says why the final attempt failed.
43    CutbacksExhausted {
44        step: usize,
45        attempts: usize,
46        radius: f64,
47        last_failure: ArcFailure,
48    },
49    /// An arc-length stop criterion was already met; the phase is over and
50    /// further steps are refused without changing any state.
51    ContinuationComplete,
52    /// The model failed `Domain::validate` (for example a nodal load on a
53    /// DOF no element stiffens).
54    InvalidModel(crate::model::ModelError),
55}
56
57/// Why one arc-length attempt was rejected. Attempts are retried with a
58/// smaller radius; this only surfaces through
59/// `AnalysisError::CutbacksExhausted`.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub enum ArcFailure {
62    /// The iteration budget ran out before every criterion passed.
63    NotConverged,
64    /// Several iterations made no meaningful progress on the merit function.
65    Stagnated,
66    /// Coupled backtracking found no step length that decreases the merit
67    /// function.
68    NoDescent,
69    /// A trial state, residual or correction was not finite.
70    NonFinite,
71    /// The bordered system was singular.
72    SingularSystem,
73    /// The bordered solve's scaled backward error stayed above target after
74    /// refinement.
75    InaccurateSolve,
76    /// The converged increment pointed backward along the path.
77    BranchOrientation,
78    /// The iterate returned to the committed point, where the constraint
79    /// row vanishes.
80    DegenerateConstraint,
81}
carapace_core/analysis/error.rs

carapace_core/analysis/
error.rs
