@ferscloud/fers-calculation-web 0.2.50 → 0.2.52

package/fers-models.d.ts

@@ -216,23 +216,51 @@ export interface components {
          *     `K·φ = λ·(−K_g)·φ` where `K_g` is the geometric stiffness from the
          *     reference load's first-order stress state. Reports the lowest positive
          *     critical load factors `α_cr = λ` and their buckling mode shapes.
+         *
+         *     Exactly one reference form must be given: `reference` (single),
+         *     `references` (explicit list), or `all_combinations: true` (every load
+         *     combination in the model). With more than one effective reference, each
+         *     runs as its own analysis — its own StiffnessCurve support/hinge
+         *     linearization and its own geometric stiffness — and the per-reference
+         *     results are reported in `results.buckling_runs` (with
+         *     `results.buckling` carrying the first successful run for backward
+         *     compatibility).
          */
         BucklingAnalysisSettings: {
+            /**
+             * @description Run one buckling analysis per load combination in the model. Takes
+             *     precedence over `reference` and `references`.
+             */
+            all_combinations?: boolean | null;
             /**
              * Format: int32
              * @description Maximum subspace-iteration sweeps. Defaults to 100 when omitted.
              */
             max_iterations?: number | null;
+            /**
+             * @description Compute per-member critical-load-method effective lengths
+             *     (`results.buckling.member_effective_lengths`). Off by default — the
+             *     output adds two entries per member.
+             */
+            member_effective_lengths?: boolean | null;
             /**
              * Format: int32
              * @description Number of buckling modes (lowest positive critical factors) to extract.
              */
             num_modes: number;
             /**
-             * @description Reference load whose first-order stress state drives the geometric
-             *     stiffness `K_g`.
+             * Format: double
+             * @description Minimum member-set share of the geometric-stiffness quadratic a mode
+             *     must have to be considered relevant for a member's effective length.
+             *     Defaults to 0.05 when omitted.
              */
-            reference: components["schemas"]["EigenLoadRef"];
+            participation_threshold?: number | null;
+            reference?: null | components["schemas"]["EigenLoadRef"];
+            /**
+             * @description Explicit list of reference loads to analyse, each as an independent
+             *     buckling run. Takes precedence over `reference`.
+             */
+            references?: components["schemas"]["EigenLoadRef"][] | null;
             /**
              * Format: double
              * @description Eigen convergence tolerance (relative change in the tracked eigenvalues
@@ -248,6 +276,7 @@ export interface components {
         BucklingCurve: "A0" | "A" | "B" | "C" | "D";
         /** @description A single linear buckling mode. */
         BucklingMode: {
+            classification?: null | components["schemas"]["BucklingModeClassification"];
             /**
              * Format: double
              * @description Critical load factor `α_cr = λ`. The structure buckles when the reference
@@ -266,7 +295,75 @@ export interface components {
              * @description 1-based mode number (1 = lowest critical load factor).
              */
             mode: number;
+            /**
+             * @description Share of the geometric-stiffness quadratic `φᵀ·K_g·φ` carried by each
+             *     member set (by set id): the buckling analogue of modal mass
+             *     participation. Shares are computed from absolute per-member
+             *     contributions; they sum to 1 when every contributing member belongs
+             *     to a member set (members outside any set count toward the total but
+             *     appear under no key, and a member listed in several sets is credited
+             *     to the first set in model order). High share = this eigenvalue
+             *     belongs to that set's members.
+             */
+            participation_by_member_set?: {
+                [key: string]: number;
+            } | null;
+        };
+        /**
+         * @description Shape-derived metadata for one buckling mode.
+         *
+         *     Label rules (checked in order, thresholds fixed and documented here):
+         *     `local` when `participating_node_fraction ≤ 0.15`; else `torsional` when
+         *     `twist_fraction ≥ 0.5`; else `sway_*` when the dominant axis holds ≥ 0.6
+         *     of the translational energy; else `mixed`. The vertical axis is taken
+         *     opposite to the model's gravity direction (global +Y when gravity is
+         *     absent or zero).
+         */
+        BucklingModeClassification: {
+            /**
+             * Format: int32
+             * @description Harmonic number along the height for sway/torsional characters:
+             *     1 + the number of sign changes of the level-mean sway (or level-twist)
+             *     profile over the vertical axis. `null` for local/mixed labels.
+             */
+            harmonic?: number | null;
+            /** @description Suggested mode character (see label rules above). */
+            label: components["schemas"]["BucklingModeLabel"];
+            /**
+             * Format: double
+             * @description Effective fraction of nodes participating in the mode: the inverse
+             *     participation ratio `(Σe)²/Σe²` of nodal translational energies,
+             *     divided by the node count. Small values mean the motion localizes in
+             *     few nodes regardless of model size.
+             */
+            participating_node_fraction: number;
+            /**
+             * Format: double
+             * @description Translational-energy share of the top 1 % of nodes (at least one
+             *     node). A single-element local mode on a large model approaches 1; a
+             *     global mode stays near the ~1–2 % a uniform shape would give.
+             */
+            top_node_energy_fraction: number;
+            /**
+             * @description Fractions of the translational mode energy (`Σ d²`) per global axis
+             *     `[X, Y, Z]`; the three sum to 1 for any mode with translational motion.
+             */
+            translation_fractions: number[];
+            /**
+             * Format: double
+             * @description Fraction of the horizontal translational energy explained by the
+             *     best-fit rigid plan rotation about the vertical axis (1 = pure twist,
+             *     0 = pure translation).
+             */
+            twist_fraction: number;
         };
+        /**
+         * @description Suggested character of a buckling mode, computed from the mode shape the
+         *     engine already holds. The label is a heuristic aid for mode selection; the
+         *     underlying fractions are reported so consumers can apply their own rules.
+         * @enum {string}
+         */
+        BucklingModeLabel: "sway_x" | "sway_y" | "sway_z" | "torsional" | "local" | "mixed";
         /**
          * @description A buckling restraint located at a node along a member set (one physical beam).
          *
@@ -299,7 +396,31 @@ export interface components {
          *     critical load factors and their buckling mode shapes.
          */
         BucklingResults: {
+            /**
+             * @description The member-hinge stiffnesses the eigenproblem actually used for
+             *     StiffnessCurve hinge DOFs — the reference member-end-force secants.
+             *     Reported per member end and DOF in user units. Absent when the model
+             *     has no StiffnessCurve member hinges.
+             */
+            linearized_hinge_stiffness?: components["schemas"]["LinearizedHingeStiffness"][] | null;
+            /**
+             * @description The support spring stiffnesses the eigenproblem actually used — for
+             *     StiffnessCurve supports these are the reference-reaction secants, for
+             *     constant springs the constant value. Reported per supported node and
+             *     DOF in user units (force/length for translations, moment/radian for
+             *     rotations). Absent when the model has no support springs.
+             */
+            linearized_support_stiffness?: components["schemas"]["LinearizedSupportStiffness"][] | null;
+            /**
+             * @description Per-member critical-load-method effective lengths, populated when
+             *     `analysis.buckling.member_effective_lengths` is enabled. Members whose
+             *     governing axial force is tensile, below the compression cutoff, or that
+             *     participate in none of the computed modes report `null` for the
+             *     affected direction — never a sentinel length.
+             */
+            member_effective_lengths?: components["schemas"]["MemberEffectiveLengths"][] | null;
             modes: components["schemas"]["BucklingMode"][];
+            reference?: null | components["schemas"]["EigenLoadRef"];
             /**
              * @description Advisories that qualify these results — e.g. model content the
              *     geometric stiffness does not cover. Empty when α_cr is unqualified.
@@ -307,6 +428,21 @@ export interface components {
              */
             warnings: components["schemas"]["SolverMessage"][];
         };
+        /**
+         * @description One buckling analysis run for one reference load, used when
+         *     `analysis.buckling` requests multiple references. Exactly one of
+         *     `results` / `error` is populated — a failed reference reports its error
+         *     here instead of silently dropping or failing the whole analysis.
+         */
+        BucklingRun: {
+            error?: string | null;
+            /**
+             * @description The reference load this run linearized at (its own spring/hinge
+             *     secants and geometric stiffness).
+             */
+            reference: components["schemas"]["EigenLoadRef"];
+            results?: null | components["schemas"]["BucklingResults"];
+        };
         /**
          * @description One line of the transparent hand-calc: a symbolic formula, the same formula
          *     with real numbers substituted, and the resulting value + unit (display units).
@@ -493,6 +629,37 @@ export interface components {
              */
             z_g: number;
         };
+        /**
+         * @description One assigned effective length: `L_cr = π·√(E·I / (λ_mode·|N|))`, with the
+         *     mode id, eigenvalue, and member axial force recorded so the number is
+         *     auditable. The engine applies no system-length cap — capping (e.g.
+         *     `min(system length, L_cr)`) is a design-code decision left to consumers.
+         */
+        EffectiveLengthValue: {
+            /**
+             * Format: double
+             * @description Reference axial force `N` of the member (compression reported
+             *     positive) in user force units.
+             */
+            axial_force: number;
+            /**
+             * Format: double
+             * @description Critical load factor `λ` of that mode.
+             */
+            critical_load_factor: number;
+            /**
+             * Format: double
+             * @description Effective (buckling) length in user length units.
+             */
+            effective_length: number;
+            /**
+             * Format: int32
+             * @description 1-based id of the mode this length was derived from — the lowest
+             *     computed mode whose member-set participation meets the threshold and
+             *     whose shape bends this member in the matching plane.
+             */
+            mode: number;
+        };
         /**
          * @description Which load drives the reference stress state for a linear buckling analysis.
          *     Its first-order member axial forces scale linearly with the load, so the
@@ -694,6 +861,11 @@ export interface components {
          * @enum {string}
          */
         GroundType: "A" | "B" | "C" | "D" | "E";
+        /**
+         * @description Local member-hinge DOF label (member local axes).
+         * @enum {string}
+         */
+        HingeDofLabel: "vx" | "vy" | "vz" | "mx" | "my" | "mz";
         /** @description Geometric imperfections (sway/translation) applied for a set of load combinations. */
         ImperfectionCase: {
             /** Format: int32 */
@@ -716,6 +888,34 @@ export interface components {
         LengthUnit: "mm" | "cm" | "m";
         /** @enum {string} */
         LimitState: "SLS" | "ULS" | "FLS" | "ALS";
+        /**
+         * @description One StiffnessCurve hinge DOF stiffness as used by the buckling
+         *     eigenproblem (the secant at the reference member-end forces).
+         */
+        LinearizedHingeStiffness: {
+            dof: components["schemas"]["HingeDofLabel"];
+            end: components["schemas"]["MemberEndLabel"];
+            /** Format: int32 */
+            member_id: number;
+            /**
+             * Format: double
+             * @description Stiffness in user units: force/length for vx/vy/vz, moment/radian
+             *     for mx/my/mz.
+             */
+            stiffness: number;
+        };
+        /** @description One support spring stiffness as used by the buckling eigenproblem. */
+        LinearizedSupportStiffness: {
+            dof: components["schemas"]["SupportDofLabel"];
+            /** Format: int32 */
+            node_id: number;
+            /**
+             * Format: double
+             * @description Spring stiffness in user units: force/length for X/Y/Z,
+             *     moment/radian for RX/RY/RZ, bimoment/radian (F·L²) for warping.
+             */
+            stiffness: number;
+        };
         /**
          * @description The coordinate frame a member point load/moment direction is expressed in.
          * @enum {string}
@@ -889,6 +1089,23 @@ export interface components {
              */
             x_frac: number;
         };
+        /**
+         * @description Critical-load-method effective lengths for one member, per principal
+         *     bending direction. `about_y` covers flexural buckling about the member's
+         *     local y-axis (deflection in local z, stiffness `E·I_y`); `about_z` covers
+         *     buckling about local z (deflection in local y, stiffness `E·I_z`).
+         */
+        MemberEffectiveLengths: {
+            about_y?: null | components["schemas"]["EffectiveLengthValue"];
+            about_z?: null | components["schemas"]["EffectiveLengthValue"];
+            /** Format: int32 */
+            member_id: number;
+        };
+        /**
+         * @description Which end of a member a hinge value belongs to.
+         * @enum {string}
+         */
+        MemberEndLabel: "start" | "end";
         /**
          * @description A rigid offset between a member end and its node, in the **global** frame
          *     (`X`, `Y`, `Z`).
@@ -1165,6 +1382,15 @@ export interface components {
          *     `weight / |gravity_factor|`).
          */
         ModalAnalysisSettings: {
+            /**
+             * @description Include the geometric (stress) stiffness of the `stiffness_reference`
+             *     state in the modal K: compression lowers the frequencies (classic
+             *     `f(P) = f₀·√(1 − P/P_cr)` behavior), tension raises them. Requires
+             *     `stiffness_reference`. If the structure is unstable at the reference
+             *     load (α_cr ≤ 1, K + K_g not positive semi-definite) the analysis
+             *     errors instead of reporting frequencies of an unstable state.
+             */
+            include_geometric_stiffness?: boolean | null;
             /** @description Mass-matrix formulation (Consistent default, Lumped optional). */
             mass_formulation?: components["schemas"]["MassFormulation"];
             /**
@@ -1177,6 +1403,7 @@ export interface components {
              * @description Number of natural modes (lowest frequencies) to extract.
              */
             num_modes: number;
+            stiffness_reference?: null | components["schemas"]["EigenLoadRef"];
             /**
              * Format: double
              * @description Eigen convergence tolerance (relative change in the tracked eigenvalues
@@ -1201,6 +1428,12 @@ export interface components {
          */
         ModalResults: {
             modes: components["schemas"]["ModeShape"][];
+            /**
+             * @description Advisories that qualify these results — e.g. a `stiffness_reference`
+             *     curve linearization that did not converge. Empty otherwise.
+             * @default []
+             */
+            warnings: components["schemas"]["SolverMessage"][];
         };
         /** @description A single natural vibration mode. */
         ModeShape: {
@@ -2009,6 +2242,13 @@ export interface components {
         /** @description All analysis results: per load case, per load combination, unity-check results and the optional HTML report. */
         ResultsBundle: {
             buckling?: null | components["schemas"]["BucklingResults"];
+            /**
+             * @description Per-reference buckling runs, present only when `analysis.buckling`
+             *     requested more than one reference (`references` /
+             *     `all_combinations`). Each run reports either results or its own
+             *     error — a failed reference never silently drops.
+             */
+            buckling_runs?: components["schemas"]["BucklingRun"][] | null;
             /**
              * @description Version of the `fers_calculations` engine that produced these results.
              *
@@ -2186,6 +2426,19 @@ export interface components {
             directional_combination?: components["schemas"]["DirectionalCombination"];
             /** @description Excitation directions to analyze (default `[X, Y]`). */
             directions?: components["schemas"]["SeismicDirection"][];
+            /**
+             * @description Include the geometric (stress) stiffness of the `stiffness_reference`
+             *     state in the seismic eigen K: gravity preload lengthens the periods
+             *     and shifts the spectral response accordingly. Requires
+             *     `stiffness_reference`. Errors when the structure is unstable at the
+             *     reference load (α_cr ≤ 1). The preload acts through the eigenpairs
+             *     (periods and mode shapes) only: the equivalent-lateral-force static
+             *     response and all member-force/reaction recovery use the elastic
+             *     (reference-linearized) stiffness, keeping recovered forces in
+             *     equilibrium with the applied loads (see the
+             *     `preload_recovery_elastic_forces` advisory).
+             */
+            include_geometric_stiffness?: boolean | null;
             /**
              * @description Include structural self-mass (density·area + weight override) in the
              *     seismic mass. Default true.
@@ -2213,6 +2466,7 @@ export interface components {
             spectrum_x: components["schemas"]["ResponseSpectrum"];
             spectrum_y?: null | components["schemas"]["ResponseSpectrum"];
             spectrum_z?: null | components["schemas"]["ResponseSpectrum"];
+            stiffness_reference?: null | components["schemas"]["EigenLoadRef"];
             /**
              * Format: double
              * @description Eigen convergence tolerance (default 1e-6).
@@ -2309,6 +2563,12 @@ export interface components {
         SeismicResults: {
             lateral_force?: null | components["schemas"]["LateralForceResults"];
             modal_response_spectrum?: null | components["schemas"]["MrsaResults"];
+            /**
+             * @description Advisories that qualify these results — e.g. a `stiffness_reference`
+             *     curve linearization that did not converge. Empty otherwise.
+             * @default []
+             */
+            warnings: components["schemas"]["SolverMessage"][];
         };
         /** @description Top-level settings: general project info and the unit system. */
         Settings: {
@@ -2426,6 +2686,11 @@ export interface components {
         };
         /** @enum {string} */
         SupportConditionType: "Fixed" | "Free" | "Spring" | "PositiveOnly" | "NegativeOnly";
+        /**
+         * @description Global support DOF label for reporting linearized spring stiffnesses.
+         * @enum {string}
+         */
+        SupportDofLabel: "X" | "Y" | "Z" | "RX" | "RY" | "RZ" | "WARPING";
         /**
          * @description Which global reaction component a **support** stiffness curve depends on.
          *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferscloud/fers-calculation-web",
   "type": "module",
-  "version": "0.2.50",
+  "version": "0.2.52",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",