section-properties 0.3.0

Structural cross-section properties: geometric/principal moments, section moduli, warping/torsion FEM, plastic, cold-formed, and fire analysis.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
//! 2D frame façade over the verified Beam FEM core (Phase 13).
//!
//! This module adds **no mechanics**. Every element stiffness, coordinate
//! transformation, load vector, static-condensation step, end-force recovery
//! and solver call is delegated to [`BeamModel`] / [`BeamSolver`]. What it adds
//! is a frame-shaped surface:
//!
//! * typed [`NodeHandle`] / [`MemberHandle`] addressing instead of positional
//!   indices;
//! * connectivity validation (orphan nodes, disconnected components, duplicate
//!   and zero-length members) with *targeted* diagnostics that replace the
//!   opaque "singular matrix" error;
//! * a support vocabulary ([`FrameModel::fix`], [`FrameModel::pin`],
//!   [`FrameModel::roller_y`], [`FrameModel::roller_x`],
//!   [`FrameModel::restrain`]);
//! * frame-level result access and a global equilibrium report.
//!
//! # Conventions (frozen - identical to `docs/beam_fem.md`)
//!
//! ```text
//! DOFs              [ux, uy, rz] per node (global), rz counter-clockwise positive
//! nodal loads       GLOBAL   (add via FrameModel::nodal_load / nodal_moment)
//! member loads      LOCAL    (add via FrameModel::member_udl / member_point_load)
//! member end forces f_end = f_equiv - K_e u_e   (element-on-node, LOCAL axes)
//! reactions         R = K_original u - f_global (global)
//! constraints       static condensation K_ff u_f = f_f - K_fc u_c (no penalties)
//! ```
//!
//! A member point load at `xi = 0` or `xi = 1` acts at a node and is **not**
//! double counted.
//!
//! # Current limitations (documented, not defects)
//!
//! * Parallel members between the same node pair are **not** supported: the
//!   second one is rejected as a duplicate. Rigid offsets / releases are not
//!   modelled.
//! * A single connected structural system is required; multiple independent
//!   substructures are rejected as disconnected.
//! * Member loads are uniform (single `(qx, qy)` per member per call; repeated
//!   calls accumulate, matching the core behaviour).
//!
//! # Example
//!
//! ```rust
//! use section_properties::frame::FrameModel;
//! use section_properties::{BeamSection, Dof, Material};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut frame = FrameModel::new();
//! let base = frame.add_node(0.0, 0.0)?;
//! let tip = frame.add_node(2.0, 0.0)?;
//! frame.add_member(base, tip, Material::new(200e9, 0.3, 7850.0, "Steel"),
//!                   BeamSection::new(5e-3, 2e-5))?;
//! frame.fix(base)?;
//! frame.nodal_load(tip, 0.0, -1.0e4)?;
//!
//! let result = frame.solve()?;
//! // v = -P L^3 / 3EI
//! let uy = result.displacement(tip, Dof::Uy)?;
//! assert!((uy + 1.0e4 * 2.0f64.powi(3) / (3.0 * 200e9 * 2e-5)).abs() < 1e-12);
//! assert!(result.equilibrium().is_balanced());
//! # Ok(())
//! # }
//! ```

use crate::SolverSelection;
use crate::beam_fem::{
    BeamElement, BeamModel, BeamNode, BeamSection, BeamSolver, Dof, FemError, ReducedSystem,
};
use crate::fea::mechanism::diagnose_reduced;
use crate::material::Material;

use std::collections::VecDeque;

pub use crate::fea::mechanism::StructuralDiagnostic;

// ---------------------------------------------------------------------------
// Handles
// ---------------------------------------------------------------------------

/// Handle to a node of a [`FrameModel`].
///
/// Handles are produced by [`FrameModel::add_node`] and are only valid for the
/// model that created them. They are deliberately distinct from raw DOF
/// indices so a node reference cannot be confused with a degree of freedom.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct NodeHandle(usize);

impl NodeHandle {
    /// The zero-based index of the node inside the model.
    pub fn index(self) -> usize {
        self.0
    }

    /// Build a handle from a raw index.
    ///
    /// The handle is **not** validated here; validity is checked when it is
    /// used against a model (returning [`FemError::InvalidNode`]). Prefer
    /// [`FrameModel::add_node`] in normal use.
    pub fn from_index(index: usize) -> Self {
        Self(index)
    }
}

/// Handle to a member (two-node frame element) of a [`FrameModel`].
///
/// Produced by [`FrameModel::add_member`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MemberHandle(usize);

impl MemberHandle {
    /// The zero-based index of the member inside the model.
    pub fn index(self) -> usize {
        self.0
    }

    /// Build a handle from a raw index.
    ///
    /// The handle is **not** validated here; validity is checked when it is
    /// used against a model (returning [`FemError::InvalidMember`]). Prefer
    /// [`FrameModel::add_member`] in normal use.
    pub fn from_index(index: usize) -> Self {
        Self(index)
    }
}

// ---------------------------------------------------------------------------
// Equilibrium report
// ---------------------------------------------------------------------------

/// Relative equilibrium tolerance: residuals are compared against the analysed
/// system's **own** force and moment magnitudes, never against an absolute
/// floor, so the verdict is invariant under a change of units (N/m ↔ kN/mm).
const EQUILIBRIUM_REL_TOL: f64 = 1e-6;

/// Conditioning-relief coefficient for [`EquilibriumReport::is_balanced`].
///
/// A Euler–Bernoulli frame's stiffness matrix is ill-conditioned when its
/// transverse/axial stiffness ratio grows: for an element the dominant
/// conditioning driver is `A·L²/I = (L/r)²`, the square of the slenderness
/// ratio `L/r` (with `r² = I/A` the radius of gyration). The forward error of a
/// direct solve is `O((L/r)² · ε)`, so equilibrium residuals — which inherit
/// that error through the recovered reactions — can legitimately reach the same
/// relative magnitude at large slenderness. A fixed `EQUILIBRIUM_REL_TOL` would
/// then flag a physically balanced frame as unbalanced (catastrophic
/// cancellation of large opposing reactions).
///
/// `effective_rel_tol = max(EQUILIBRIUM_REL_TOL, C · λ²_max · ε)` recovers the
/// correct verdict: `λ²_max = max_elements(L²·A/I)` is a **dimensionless** and
/// **unit-invariant** element-level slenderness/conditioning proxy (a consistent
/// change of the length/area/inertia units multiplies numerator and denominator
/// by the same power, leaving the ratio unchanged), so the tolerance itself is
/// dimensionless and unit-invariant. It is not a strict bound on the full
/// assembled stiffness matrix condition number — the global conditioning may be
/// worse — but it captures the dominant per-element driver and biases the
/// tolerance toward being tight rather than loose.
///
/// `C = 1e-2` is an **empirically calibrated** safety factor, not a rigorous
/// error upper bound. It was calibrated against the measured residual of a
/// large-scale symmetric hyperstatic portal regression case (`λ² ≈ 2.5e14`,
/// measured residual `~1.7e-3 · λ² · ε`); the coefficient is ≪ 1 because
/// reaction cancellation reduces the residual far below the pessimistic
/// forward-error bound. The calibration is based on this specific topology and
/// load pattern; other frame configurations may exhibit different cancellation
/// behaviour. Below `λ² ≈ 4.5e9` (span ≈ 42 km for the reference section) the
/// term stays below `EQUILIBRIUM_REL_TOL` and the tolerance is exactly `1e-6`,
/// unchanged.
const EQUILIBRIUM_COND_FACTOR: f64 = 1e-2;

/// Result of the global equilibrium check, summed **about the global origin
/// `(0, 0)`**.
///
/// Residuals are `applied + reaction` and should be zero for a solved,
/// properly restrained frame. Both the residuals and the contributing totals
/// are exposed so a caller can diagnose which component is out of balance
/// instead of receiving a single boolean.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EquilibriumReport {
    /// Residual of `ΣFx` (applied + reaction).
    pub fx_residual: f64,
    /// Residual of `ΣFy` (applied + reaction).
    pub fy_residual: f64,
    /// Residual of `ΣMz` about the global origin (applied + reaction).
    pub mz_residual: f64,
    /// Total applied horizontal load (global nodal, plus member load resultants).
    pub applied_fx: f64,
    /// Total applied vertical load.
    pub applied_fy: f64,
    /// Total applied moment about the origin, including force moments `x·Fy − y·Fx`.
    pub applied_mz: f64,
    /// Sum of support reaction forces in X.
    pub reaction_fx: f64,
    /// Sum of support reaction forces in Y.
    pub reaction_fy: f64,
    /// Sum of reaction moments about the origin, including `x·Ry − y·Rx`.
    pub reaction_mz: f64,
    /// Absolute **force** tolerance applied by [`Self::is_balanced`], equal to
    /// `effective_rel_tol · force_scale` (see [`Self::force_tolerance`]). The
    /// moment tolerance is **not** stored in this field; use
    /// [`Self::moment_tolerance`] to obtain it. Using `tolerance` to
    /// threshold `mz_residual` gives a wrong verdict when `l_char != 1`.
    /// Private: use [`Self::force_tolerance`] or [`Self::moment_tolerance`].
    tolerance: f64,
    /// Σ of the absolute applied and reaction **force** magnitudes actually
    /// present (per load term, not per resultant — a self-cancelling load pair
    /// must not collapse the scale to zero). Private: it only feeds
    /// [`Self::is_balanced`].
    f_mag: f64,
    /// Σ of the absolute applied and reaction **moment** magnitudes actually
    /// present, again per term. Private, as above.
    m_mag: f64,
    /// Characteristic length of the structure: the largest absolute nodal
    /// coordinate (see [`characteristic_length`]). Private, as above.
    l_char: f64,
    /// Conditioning-relief relative floor `C · λ²_max · ε`, where `λ²_max` is
    /// the maximum element slenderness squared `L²·A/I` (dimensionless,
    /// unit-invariant). `0.0` when the frame has no element. Private: it only
    /// feeds [`Self::is_balanced`]; see [`EQUILIBRIUM_COND_FACTOR`].
    cond_rel_floor: f64,
}

/// The two scale factors behind [`EquilibriumReport::is_balanced`]:
/// `(force_scale, moment_scale)`.
///
/// Both are built **only** from magnitudes the analysed system actually carries,
/// so a pure change of units (N/m ↔ kN/mm) leaves the verdict unchanged:
///
/// * `force_scale = Σ|F| + Σ|M| / l_char` — the force magnitudes present
///   (applied plus recovered reactions) plus the equivalent force of the moments
///   present, so a pure-moment system still has a positive force scale.
/// * `moment_scale = Σ|M| + Σ|F| · l_char` — the moment magnitudes present plus
///   the moment the forces produce through their largest lever arm `l_char`.
///   The `Σ|F| · l_char` term is what keeps the moment check sensitive for a load
///   system that is symmetric about the origin (`applied_mz == 0`): the scale
///   then reflects the real force × length magnitudes rather than collapsing to
///   a constant.
///
/// `Σ|F|` and `Σ|M|` are sums of absolute **per-term** magnitudes (`f_mag`,
/// `m_mag`), so equal-and-opposite terms that cancel in the resultant still keep
/// the scale positive; `l_char` is the largest absolute nodal coordinate. All
/// three are zero only for a model with no load and no reactions, in which case
/// both scales are zero and the check degenerates to "the residual must be
/// exactly zero".
fn equilibrium_scales(f_mag: f64, m_mag: f64, l_char: f64) -> (f64, f64) {
    if l_char > 0.0 {
        (f_mag + m_mag / l_char, m_mag + f_mag * l_char)
    } else {
        (f_mag, m_mag)
    }
}

impl EquilibriumReport {
    /// Whether all three residuals are within a tolerance **relative** to the
    /// analysed system's own magnitudes (see `equilibrium_scales`).
    ///
    /// The force residuals (`fx`, `fy`) are compared against `force_scale` and
    /// the moment residual (`mz`) against `moment_scale`, both scaled by the
    /// conditioning-aware effective relative tolerance
    /// `Self::effective_rel_tol`. At normal slenderness this is exactly
    /// `EQUILIBRIUM_REL_TOL` (`1e-6`); for highly slender frames it is raised
    /// by a dimensionless element-level conditioning proxy (see
    /// `EQUILIBRIUM_COND_FACTOR`) so that pure solver round-off is not
    /// mistaken for a physical imbalance. The verdict is invariant under a
    /// change of units and the moment check stays sensitive even when a load
    /// system is symmetric about the origin (`applied_mz == 0`). There is no
    /// absolute floor: if every relevant magnitude is zero the scale is zero
    /// and the residual must then be **exactly** zero for the frame to be
    /// balanced.
    pub fn is_balanced(&self) -> bool {
        let (f_scale, m_scale) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
        let rel = self.effective_rel_tol();
        self.fx_residual.abs() <= rel * f_scale
            && self.fy_residual.abs() <= rel * f_scale
            && self.mz_residual.abs() <= rel * m_scale
    }

    /// Effective relative tolerance: at least [`EQUILIBRIUM_REL_TOL`], relaxed
    /// by the conditioning floor for a slender frame so pure solver round-off
    /// is not mistaken for a physical imbalance.
    fn effective_rel_tol(&self) -> f64 {
        EQUILIBRIUM_REL_TOL.max(self.cond_rel_floor)
    }

    /// Force tolerance used by [`Self::is_balanced`]: `effective_rel_tol *
    /// force_scale`, where `force_scale = Σ|F| + Σ|M| / l_char` (see
    /// `equilibrium_scales`). The force residuals `fx_residual` and
    /// `fy_residual` are compared against this value.
    ///
    /// This is identical to the [`Self::tolerance`] field, exposed as a
    /// method for clarity and symmetry with [`Self::moment_tolerance`].
    pub fn force_tolerance(&self) -> f64 {
        let (f_scale, _) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
        self.effective_rel_tol() * f_scale
    }

    /// Moment tolerance used by [`Self::is_balanced`]: `effective_rel_tol *
    /// moment_scale`, where `moment_scale = Σ|M| + Σ|F| * l_char` (see
    /// `equilibrium_scales`). The moment residual `mz_residual` is
    /// compared against this value.
    ///
    /// This is generally **not** equal to [`Self::tolerance`] (which is the
    /// force tolerance); using `tolerance` to threshold `mz_residual` would
    /// give a wrong verdict for structures with `l_char != 1`.
    pub fn moment_tolerance(&self) -> f64 {
        let (_, m_scale) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
        self.effective_rel_tol() * m_scale
    }
}

// ---------------------------------------------------------------------------
// FrameModel
// ---------------------------------------------------------------------------

/// A 2D frame: nodes, members, supports and loads.
///
/// Wraps the existing [`BeamModel`] and delegates all mechanics to it; supports
/// arbitrary planar connectivity (not just a straight beam), per-DOF
/// constraints and prescribed displacements.
#[derive(Debug, Clone)]
pub struct FrameModel {
    inner: BeamModel,
}

impl Default for FrameModel {
    fn default() -> Self {
        Self::new()
    }
}

impl FrameModel {
    /// Create an empty frame.
    pub fn new() -> Self {
        Self {
            inner: BeamModel::new(),
        }
    }

    /// Number of nodes.
    pub fn n_nodes(&self) -> usize {
        self.inner.nodes.len()
    }

    /// Number of members.
    pub fn n_members(&self) -> usize {
        self.inner.elements.len()
    }

    /// Add a node at global `(x, y)` and return its handle.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidInput`] if either coordinate is not finite.
    pub fn add_node(&mut self, x: f64, y: f64) -> Result<NodeHandle, FemError> {
        if !x.is_finite() || !y.is_finite() {
            return Err(FemError::InvalidInput(format!(
                "node coordinates must be finite, got ({x}, {y})"
            )));
        }
        let idx = self.inner.nodes.len();
        self.inner.add_node(BeamNode::new(idx, x, y));
        Ok(NodeHandle(idx))
    }

    /// Add a member between two existing nodes.
    ///
    /// The member stiffness uses `EA` (axial) and `EI` (bending) from the given
    /// material and section, exactly as the Beam FEM core does.
    ///
    /// # Errors
    ///
    /// * [`FemError::InvalidNode`] if either handle is not valid for this model;
    /// * [`FemError::ZeroLengthMember`] if the two nodes coincide;
    /// * [`FemError::DuplicateMember`] if a member already connects the same
    ///   node pair (in either order) - parallel members are not supported;
    /// * [`FemError::InvalidInput`] if `E`, `A` or `I` is non-finite or
    ///   non-positive (the same predicate the solver applies at assembly time).
    pub fn add_member(
        &mut self,
        a: NodeHandle,
        b: NodeHandle,
        material: Material,
        section: BeamSection,
    ) -> Result<MemberHandle, FemError> {
        let ia = self.check_node(a)?;
        let ib = self.check_node(b)?;
        if ia == ib {
            return Err(FemError::ZeroLengthMember(format!(
                "member connects node {ia} to itself"
            )));
        }
        let (pa, pb) = (self.inner.nodes[ia].point(), self.inner.nodes[ib].point());
        let (dx, dy) = (pb.x - pa.x, pb.y - pa.y);
        if !dx.is_finite() || !dy.is_finite() || dx * dx + dy * dy <= 0.0 {
            return Err(FemError::ZeroLengthMember(format!(
                "nodes {ia} and {ib} coincide at ({}, {})",
                pa.x, pa.y
            )));
        }

        let (e, area, inertia) = (material.youngs_modulus, section.area, section.second_moment);
        if !e.is_finite() || e <= 0.0 {
            return Err(FemError::InvalidInput(format!(
                "Young's modulus must be finite and positive, got {e}"
            )));
        }
        if !area.is_finite() || area <= 0.0 {
            return Err(FemError::InvalidInput(format!(
                "cross-section area must be finite and positive, got {area}"
            )));
        }
        if !inertia.is_finite() || inertia <= 0.0 {
            return Err(FemError::InvalidInput(format!(
                "second moment of area must be finite and positive, got {inertia}"
            )));
        }

        let (lo, hi) = if ia < ib { (ia, ib) } else { (ib, ia) };
        for existing in &self.inner.elements {
            let (elo, ehi) = if existing.node_i < existing.node_j {
                (existing.node_i, existing.node_j)
            } else {
                (existing.node_j, existing.node_i)
            };
            if elo == lo && ehi == hi {
                return Err(FemError::DuplicateMember(format!(
                    "a member already connects nodes {lo} and {hi}; parallel members are not supported"
                )));
            }
        }

        let element = BeamElement::new(ia, ib, material, section)?;
        self.inner.add_element(element);
        Ok(MemberHandle(self.inner.elements.len() - 1))
    }

    /// Fully fix a node (`ux = uy = rz = 0`).
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    /// [`FemError::ConflictingPrescribedDisplacement`] if any of the node's
    /// DOFs already has a conflicting prescribed value.
    pub fn fix(&mut self, node: NodeHandle) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.try_fix_node(i)
    }

    /// Pin a node: restrain `ux` and `uy`, leave the rotation free.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    /// [`FemError::ConflictingPrescribedDisplacement`] if either `ux` or `uy`
    /// already has a conflicting prescribed value.
    pub fn pin(&mut self, node: NodeHandle) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.try_fix_dof(i, Dof::Ux.index(), 0.0)?;
        self.inner.try_fix_dof(i, Dof::Uy.index(), 0.0)
    }

    /// Roller restraining the vertical translation (`uy = 0`), horizontal free.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    /// [`FemError::ConflictingPrescribedDisplacement`] if `uy` already has a
    /// conflicting prescribed value.
    pub fn roller_y(&mut self, node: NodeHandle) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.try_fix_dof(i, Dof::Uy.index(), 0.0)
    }

    /// Roller restraining the horizontal translation (`ux = 0`), vertical free.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    /// [`FemError::ConflictingPrescribedDisplacement`] if `ux` already has a
    /// conflicting prescribed value.
    pub fn roller_x(&mut self, node: NodeHandle) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.try_fix_dof(i, Dof::Ux.index(), 0.0)
    }

    /// Prescribe a DOF to an arbitrary finite value (e.g. a support settlement).
    ///
    /// Applied through the existing static condensation
    /// (`K_ff u_f = f_f - K_fc u_c`); no penalty constraints are used.
    ///
    /// If the DOF was previously constrained (e.g. by [`fix`](Self::fix)),
    /// the existing prescription is **replaced** — this allows the common
    /// workflow of fixing a support node and then applying a settlement.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    /// [`FemError::InvalidInput`] if `value` is not finite.
    pub fn restrain(&mut self, node: NodeHandle, dof: Dof, value: f64) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.try_override(i, dof, value)
    }

    /// Apply a **global** nodal force `(fx, fy)`.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid, or
    /// [`FemError::InvalidInput`] if either component is non-finite. Both
    /// components are validated **before** either is recorded, so a rejected
    /// call leaves the model unchanged (no half-applied load).
    pub fn nodal_load(&mut self, node: NodeHandle, fx: f64, fy: f64) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        if !fx.is_finite() {
            return Err(FemError::InvalidInput(format!(
                "nodal force Fx must be finite, got {fx}"
            )));
        }
        if !fy.is_finite() {
            return Err(FemError::InvalidInput(format!(
                "nodal force Fy must be finite, got {fy}"
            )));
        }
        self.inner.try_add_nodal_force(i, Dof::Ux.index(), fx)?;
        self.inner.try_add_nodal_force(i, Dof::Uy.index(), fy)
    }

    /// Apply a **global** nodal moment `mz` (counter-clockwise positive).
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid.
    pub fn nodal_moment(&mut self, node: NodeHandle, mz: f64) -> Result<(), FemError> {
        let i = self.check_node(node)?;
        self.inner.add_applied_moment(i, mz)
    }

    /// Apply a uniform distributed load in the member's **local** axes.
    ///
    /// `qy > 0` is upward in local +y; `qx > 0` is tensile (towards `node_j`).
    /// Repeated calls accumulate on the same member.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidMember`] if the handle is not valid.
    pub fn member_udl(&mut self, member: MemberHandle, qx: f64, qy: f64) -> Result<(), FemError> {
        let i = self.check_member(member)?;
        self.inner.add_distributed_load(i, qx, qy)
    }

    /// Apply a point load in the member's **local** axes at normalised position
    /// `xi in [0, 1]`.
    ///
    /// `xi = 0` / `xi = 1` places the load at a node; it is applied exactly once
    /// (no double counting).
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidMember`] if the handle is not valid.
    pub fn member_point_load(
        &mut self,
        member: MemberHandle,
        xi: f64,
        fx: f64,
        fy: f64,
        mz: f64,
    ) -> Result<(), FemError> {
        let i = self.check_member(member)?;
        self.inner.add_point_load(i, xi, fx, fy, mz)
    }

    /// Solve with automatic solver selection.
    ///
    /// Equivalent to `self.solve_with(SolverSelection::Auto)`. The registry
    /// inspects the condensed stiffness matrix and picks a backend (dense for
    /// small systems, skyline LDLᵀ for symmetric positive-definite, sparse LU
    /// otherwise). The selected solver is used exactly once; if it fails the
    /// error is returned directly — there is no automatic retry with a
    /// different backend.
    ///
    /// # Errors
    ///
    /// Returns [`FemError`] if the model is invalid (see [`Self::validate`]),
    /// the stiffness matrix is singular/near-singular, or the solver backend
    /// fails.
    pub fn solve(&self) -> Result<FrameAnalysisResult, FemError> {
        self.solve_with(SolverSelection::Auto)
    }

    /// Solve with an explicit backend selection.
    ///
    /// Validates the model (see [`Self::validate`]) before assembling, so
    /// structural modelling errors are reported as targeted diagnostics rather
    /// than as a matrix singularity.
    ///
    /// **Solver semantics**:
    /// - [`SolverSelection::Auto`] — the registry inspects the matrix and
    ///   selects a backend. The chosen solver is used exactly once; if it
    ///   fails, the error is returned directly (no automatic retry with a
    ///   different backend).
    /// - [`SolverSelection::Named`] — the requested solver is used **only**;
    ///   no silent fallback. If the solver is unavailable or fails, the error
    ///   is returned directly. Use the convenience constructors
    ///   [`SolverSelection::dense`], [`SolverSelection::skyline_ldlt`],
    ///   [`SolverSelection::sparse_lu`], [`SolverSelection::cg`],
    ///   [`SolverSelection::iccg`] for typed selection.
    ///
    /// After solving, [`FrameAnalysisResult::solver_name`] reports which
    /// backend was actually used.
    ///
    /// # Errors
    ///
    /// Returns [`FemError`] if the model is invalid, the requested solver is
    /// unavailable, or the solve fails (singular/near-singular matrix).
    pub fn solve_with(&self, selection: SolverSelection) -> Result<FrameAnalysisResult, FemError> {
        FrameSolver::new(self).with_selection(selection).solve()
    }

    /// A solver builder for this frame (configure a backend, then solve).
    pub fn solver(&self) -> FrameSolver<'_> {
        FrameSolver::new(self)
    }

    /// Validate the structural model.
    ///
    /// Checks, in order:
    ///
    /// 1. the model is not empty (at least one node and one member);
    /// 2. no **orphan nodes** - every node is used by at least one member;
    /// 3. the members form a **single connected component**.
    ///
    /// Per-element checks (zero length, duplicate connectivity, invalid
    /// material/section) are enforced when the member is added.
    ///
    /// Insufficient restraint is *not* diagnosed here: [`Self::diagnostic`]
    /// classifies the boundary-conditioned system separately, without
    /// rejecting the model, and [`FrameSolver::solve`] attaches that
    /// classification to the solver error when the solve fails.
    pub fn validate(&self) -> Result<(), FemError> {
        let inner = &self.inner;
        if inner.nodes.is_empty() {
            return Err(FemError::InvalidModel(
                "frame has no nodes; add at least one node and one member".to_string(),
            ));
        }
        if inner.elements.is_empty() {
            return Err(FemError::InvalidModel(
                "frame has no members; add at least one member".to_string(),
            ));
        }

        let mut used = vec![false; inner.nodes.len()];
        for e in &inner.elements {
            used[e.node_i] = true;
            used[e.node_j] = true;
        }
        if let Some(i) = used.iter().position(|u| !u) {
            let p = inner.nodes[i].point();
            return Err(FemError::OrphanNode(format!(
                "node {i} at ({}, {}) is not connected to any member",
                p.x, p.y
            )));
        }

        let components = count_components(inner.nodes.len(), &inner.elements);
        if components > 1 {
            return Err(FemError::DisconnectedStructure(format!(
                "frame has {components} disconnected components; a single connected \
                 structural system is required"
            )));
        }
        Ok(())
    }

    /// Diagnose the **boundary-conditioned** (reduced) system without solving
    /// it: is this structure stable, under-restrained (rigid-body mechanism),
    /// internally rank deficient (mechanism), or merely numerically
    /// ill-conditioned?
    ///
    /// The diagnosis reads the reduced free-free stiffness block `K_ff` that
    /// the **actual solve path** condenses (`BeamSolver::condense`) — the exact
    /// matrix a solve factorises, not a second assembly — and classifies it with
    /// relative, scale-invariant probes (see [`crate::fea::mechanism`] for the
    /// criterion and its limits). It never assembles with penalties, never
    /// perturbs the matrix and never fabricates displacements, and it does not
    /// run as part of a successful [`Self::solve`].
    ///
    /// The verdict is a property of the **structure**, not of the loads: the
    /// load vector is not consulted, so scaling or omitting the loads cannot
    /// change the result.
    ///
    /// # Errors
    ///
    /// The same model errors as [`Self::solve`]: [`Self::validate`] plus the
    /// construction checks [`BeamSolver::from_model`] performs (its error
    /// surface is slightly wider than `validate` alone).
    pub fn diagnostic(&self) -> Result<StructuralDiagnostic, FemError> {
        self.validate()?;
        let mut beam = BeamSolver::from_model(&self.inner)?;
        Ok(self.classify(beam.condense()))
    }

    /// Classify a reduced (boundary-conditioned) stiffness system using this
    /// model's geometry: the global rigid-body motions are built in *reduced*
    /// order from the solver's own free-DOF map, so no independent reassembly
    /// of `K_ff` is involved.
    fn classify(&self, reduced: &ReducedSystem) -> StructuralDiagnostic {
        let rigid = self.rigid_candidates(reduced.free_to_global());
        diagnose_reduced(reduced.k_ff(), &rigid)
    }

    /// The three global rigid-body motions (Tx, Ty, Rz) restricted to the free
    /// DOFs, laid out in reduced order.
    ///
    /// `free_to_global[r]` is the global DOF (`3 * node + dof`) of reduced index
    /// `r`; constrained entries are dropped, not displaced. Rotation by `theta`
    /// about the global origin is `ux = -theta*y`, `uy = theta*x`, `rz = theta`.
    fn rigid_candidates(&self, free_to_global: &[usize]) -> Vec<Vec<f64>> {
        let n_free = free_to_global.len();
        let mut tx = vec![0.0; n_free];
        let mut ty = vec![0.0; n_free];
        let mut rz = vec![0.0; n_free];
        for (r, &global) in free_to_global.iter().enumerate() {
            let point = self.inner.nodes[global / 3].point();
            match global % 3 {
                0 => {
                    tx[r] = 1.0;
                    rz[r] = -point.y;
                }
                1 => {
                    ty[r] = 1.0;
                    rz[r] = point.x;
                }
                _ => rz[r] = 1.0,
            }
        }
        vec![tx, ty, rz]
    }

    /// Handle of the node with the given index.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the index is out of range.
    pub fn node_handle(&self, index: usize) -> Result<NodeHandle, FemError> {
        if index >= self.inner.nodes.len() {
            return Err(FemError::InvalidNode(format!(
                "node index {index} is out of range (max: {})",
                self.inner.nodes.len().saturating_sub(1)
            )));
        }
        Ok(NodeHandle(index))
    }

    /// Handle of the member with the given index.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidMember`] if the index is out of range.
    pub fn member_handle(&self, index: usize) -> Result<MemberHandle, FemError> {
        if index >= self.inner.elements.len() {
            return Err(FemError::InvalidMember(format!(
                "member index {index} is out of range (max: {})",
                self.inner.elements.len().saturating_sub(1)
            )));
        }
        Ok(MemberHandle(index))
    }

    fn check_node(&self, node: NodeHandle) -> Result<usize, FemError> {
        if node.0 >= self.inner.nodes.len() {
            return Err(FemError::InvalidNode(format!(
                "node handle {} is not valid for this frame (max: {})",
                node.0,
                self.inner.nodes.len().saturating_sub(1)
            )));
        }
        Ok(node.0)
    }

    fn check_member(&self, member: MemberHandle) -> Result<usize, FemError> {
        if member.0 >= self.inner.elements.len() {
            return Err(FemError::InvalidMember(format!(
                "member handle {} is not valid for this frame (max: {})",
                member.0,
                self.inner.elements.len().saturating_sub(1)
            )));
        }
        Ok(member.0)
    }
}

/// Number of connected components of the member connectivity graph.
fn count_components(n_nodes: usize, elements: &[BeamElement]) -> usize {
    let mut adj: Vec<Vec<usize>> = vec![Vec::new(); n_nodes];
    for e in elements {
        adj[e.node_i].push(e.node_j);
        adj[e.node_j].push(e.node_i);
    }
    let mut seen = vec![false; n_nodes];
    let mut components = 0;
    for start in 0..n_nodes {
        if seen[start] || adj[start].is_empty() {
            continue;
        }
        components += 1;
        seen[start] = true;
        let mut queue = VecDeque::from([start]);
        while let Some(u) = queue.pop_front() {
            for &v in &adj[u] {
                if !seen[v] {
                    seen[v] = true;
                    queue.push_back(v);
                }
            }
        }
    }
    components
}

// ---------------------------------------------------------------------------
// FrameSolver
// ---------------------------------------------------------------------------

/// Solves a [`FrameModel`]; configure the backend, then [`FrameSolver::solve`].
pub struct FrameSolver<'a> {
    model: &'a FrameModel,
    selection: SolverSelection,
}

impl<'a> FrameSolver<'a> {
    /// Create a solver for `model` using automatic backend selection.
    pub fn new(model: &'a FrameModel) -> Self {
        Self {
            model,
            selection: SolverSelection::Auto,
        }
    }

    /// Choose an explicit backend (or [`SolverSelection::Auto`]).
    pub fn with_selection(mut self, selection: SolverSelection) -> Self {
        self.selection = selection;
        self
    }

    /// Set the backend (builder-style alternative to [`Self::with_selection`]).
    pub fn set_solver(&mut self, selection: SolverSelection) {
        self.selection = selection;
    }

    /// Validate, assemble and solve the frame.
    ///
    /// A successful solve runs **no** diagnostic and its numerical path is
    /// unchanged (see [`FrameModel::diagnostic`] for the on-demand API). Only a
    /// *failed* solve additionally classifies the reduced system, and appends
    /// that classification to the error message so an under-restrained or
    /// rank-deficient frame is not reported as an opaque "singular matrix".
    ///
    /// # Errors
    ///
    /// Model-structure errors from [`FrameModel::validate`] plus any
    /// [`FemError::SolverError`] from the linear solver (e.g. insufficient
    /// restraint, or a conditioning limit at extreme scales). The variant is
    /// unchanged; the message carries the diagnosis.
    pub fn solve(&self) -> Result<FrameAnalysisResult, FemError> {
        self.model.validate()?;
        let mut beam = BeamSolver::from_model(&self.model.inner)?;
        beam.set_solver(self.selection.clone());
        if let Err(e) = beam.solve_configured() {
            // The solver condensed the boundary conditions before attempting any
            // backend, so its retained reduced system is the exact matrix the
            // failed factorisation saw - no second assembly.
            let diagnosis = beam.reduced_system().map(|rs| self.model.classify(rs));
            return Err(with_structural_diagnosis(e, diagnosis));
        }
        Ok(FrameAnalysisResult {
            beam,
            model: self.model.clone(),
        })
    }
}

/// Record the structural diagnosis of a failed solve in the error message.
///
/// The error **variant** is deliberately preserved (`SolverError` stays
/// `SolverError`): the diagnosis is extra information, not a re-typing of the
/// failure, so no existing caller or exhaustive match changes meaning. A
/// `Stable` diagnosis adds nothing - the failure was not structural - and a
/// missing diagnosis (`None`, i.e. no reduced system was available) leaves the
/// error untouched.
fn with_structural_diagnosis(err: FemError, diagnosis: Option<StructuralDiagnostic>) -> FemError {
    match (err, diagnosis) {
        (FemError::SolverError { source, message }, Some(d))
            if !matches!(d, StructuralDiagnostic::Stable) =>
        {
            FemError::SolverError {
                source,
                message: format!("{message}; structural diagnosis: {d}"),
            }
        }
        (other, _) => other,
    }
}

// ---------------------------------------------------------------------------
// FrameAnalysisResult
// ---------------------------------------------------------------------------

/// Solved frame: frame-level access to displacements, reactions, member end
/// forces and global equilibrium.
///
/// All values come from the existing [`BeamSolver`]; nothing is recomputed with
/// a second formulation.
pub struct FrameAnalysisResult {
    beam: BeamSolver,
    model: FrameModel,
}

impl std::fmt::Debug for FrameAnalysisResult {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FrameAnalysisResult")
            .field("nodes", &self.model.n_nodes())
            .field("members", &self.model.n_members())
            .field("solver", &self.beam.solver_name())
            .finish_non_exhaustive()
    }
}

impl FrameAnalysisResult {
    /// Name of the backend used by the successful solve.
    pub fn solver_name(&self) -> Option<&str> {
        self.beam.solver_name()
    }

    /// Number of nodes in the solved frame.
    pub fn n_nodes(&self) -> usize {
        self.model.n_nodes()
    }

    /// Number of members in the solved frame.
    pub fn n_members(&self) -> usize {
        self.model.n_members()
    }

    /// Full global displacement vector, laid out `[ux, uy, rz]` per node.
    pub fn displacements(&self) -> &[f64] {
        self.beam.displacements()
    }

    /// Global support reactions, laid out `[Rx, Ry, Mz]` per node.
    pub fn reactions(&self) -> Vec<f64> {
        self.beam.reactions()
    }

    /// Displacement of a DOF at a node (global).
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid for this frame.
    pub fn displacement(&self, node: NodeHandle, dof: Dof) -> Result<f64, FemError> {
        self.check_node(node)?;
        self.beam.displacement_dof(node.index(), dof)
    }

    /// Support reaction of a DOF at a node (global).
    ///
    /// Free DOFs report the raw (round-off) residual, exactly as
    /// [`BeamSolver::reaction_dof`] does.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidNode`] if the handle is not valid for this frame.
    pub fn reaction(&self, node: NodeHandle, dof: Dof) -> Result<f64, FemError> {
        self.check_node(node)?;
        self.beam.reaction_dof(node.index(), dof)
    }

    /// Member end forces in **local** axes:
    /// `[N_i, V_i, M_i, N_j, V_j, M_j]`.
    ///
    /// These are element-on-node forces, `f_end = f_equiv - K_e u_e`, exactly as
    /// documented in `docs/beam_fem.md`; the sign convention is **not** inverted
    /// for the frame API.
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidMember`] if the handle is not valid for this frame.
    pub fn member_end_forces(&self, member: MemberHandle) -> Result<[f64; 6], FemError> {
        let i = self.check_member(member)?;
        let all = self.beam.element_end_forces()?;
        all.get(i)
            .copied()
            .ok_or_else(|| FemError::InvalidMember(format!("member handle {} is out of range", i)))
    }

    /// Member end forces transformed to **global** axes
    /// (`f_global = Tᵀ f_local`).
    ///
    /// # Errors
    ///
    /// [`FemError::InvalidMember`] if the handle is not valid for this frame.
    pub fn member_end_forces_global(&self, member: MemberHandle) -> Result<[f64; 6], FemError> {
        let i = self.check_member(member)?;
        let all = self.beam.element_end_forces_global()?;
        all.get(i)
            .copied()
            .ok_or_else(|| FemError::InvalidMember(format!("member handle {} is out of range", i)))
    }

    /// Global equilibrium check about the origin `(0, 0)`.
    ///
    /// Combines support reactions, global nodal loads and moments, and the
    /// global resultants of member distributed and point loads (transformed from
    /// member-local axes and applied at their true global locations).
    /// See [`EquilibriumReport`].
    pub fn equilibrium(&self) -> EquilibriumReport {
        let m = &self.model.inner;
        let mut applied_fx = 0.0;
        let mut applied_fy = 0.0;
        let mut applied_mz = 0.0;
        // Absolute per-term magnitudes (not resultants): a load pair that cancels
        // in the sum must still contribute to the equilibrium scale.
        let mut applied_f_mag = 0.0;
        let mut applied_m_mag = 0.0;

        // Global nodal loads and moments.
        for (node, dof, v) in &m.nodal_forces {
            let p = m.nodes[*node].point();
            match *dof {
                0 => {
                    applied_fx += v;
                    applied_mz += -p.y * v;
                    applied_f_mag += v.abs();
                }
                1 => {
                    applied_fy += v;
                    applied_mz += p.x * v;
                    applied_f_mag += v.abs();
                }
                _ => {
                    applied_mz += v;
                    applied_m_mag += v.abs();
                }
            }
        }
        for am in &m.applied_moments {
            applied_mz += am.value;
            applied_m_mag += am.value.abs();
        }

        // Member load resultants, rotated from local to global.
        for (elem_idx, dl) in m.distributed_loads.iter().enumerate() {
            let _ = elem_idx;
            let Some((pi, pj)) = member_points(m, dl.element_idx) else {
                continue;
            };
            let (dx, dy) = (pj.x - pi.x, pj.y - pi.y);
            let len = (dx * dx + dy * dy).sqrt();
            let (c, s) = (dx / len, dy / len);
            let (lfx, lfy) = (dl.qx * len, dl.qy * len);
            let (gx, gy) = (c * lfx - s * lfy, s * lfx + c * lfy);
            let (xm, ym) = (pi.x + 0.5 * dx, pi.y + 0.5 * dy);
            applied_fx += gx;
            applied_fy += gy;
            applied_mz += xm * gy - ym * gx;
            applied_f_mag += gx.abs() + gy.abs();
        }
        for pl in &m.point_loads {
            let Some((pi, _)) = member_points(m, pl.element_idx) else {
                continue;
            };
            let el = &m.elements[pl.element_idx];
            let pj = m.nodes[el.node_j].point();
            let (dx, dy) = (pj.x - pi.x, pj.y - pi.y);
            let len = (dx * dx + dy * dy).sqrt();
            let (c, s) = (dx / len, dy / len);
            let (gx, gy) = (c * pl.fx - s * pl.fy, s * pl.fx + c * pl.fy);
            let (xp, yp) = (pi.x + pl.position * dx, pi.y + pl.position * dy);
            applied_fx += gx;
            applied_fy += gy;
            applied_mz += xp * gy - yp * gx + pl.mz;
            applied_f_mag += gx.abs() + gy.abs();
            applied_m_mag += pl.mz.abs();
        }

        // Support reactions, per node.
        let reactions = self.beam.reactions();
        let mut reaction_fx = 0.0;
        let mut reaction_fy = 0.0;
        let mut reaction_mz = 0.0;
        let mut reaction_f_mag = 0.0;
        let mut reaction_m_mag = 0.0;
        for (idx, node) in m.nodes.iter().enumerate() {
            let p = node.point();
            let rx = reactions.get(3 * idx).copied().unwrap_or(0.0);
            let ry = reactions.get(3 * idx + 1).copied().unwrap_or(0.0);
            let rz = reactions.get(3 * idx + 2).copied().unwrap_or(0.0);
            reaction_fx += rx;
            reaction_fy += ry;
            reaction_mz += p.x * ry - p.y * rx + rz;
            reaction_f_mag += rx.abs() + ry.abs();
            reaction_m_mag += rz.abs();
        }

        // Characteristic length of the structure: the largest absolute nodal
        // coordinate. Positive for any solvable model (a zero-length member is
        // rejected). It is what makes the moment scale `Σ|F|·l_char` reflect the
        // structure rather than a constant.
        let l_char = characteristic_length(m);
        let f_mag = applied_f_mag + reaction_f_mag;
        let m_mag = applied_m_mag + reaction_m_mag;
        let cond_rel_floor = EQUILIBRIUM_COND_FACTOR * max_element_slenderness_sq(m) * f64::EPSILON;
        let rel = EQUILIBRIUM_REL_TOL.max(cond_rel_floor);
        let (f_scale, _m_scale) = equilibrium_scales(f_mag, m_mag, l_char);

        EquilibriumReport {
            fx_residual: applied_fx + reaction_fx,
            fy_residual: applied_fy + reaction_fy,
            mz_residual: applied_mz + reaction_mz,
            applied_fx,
            applied_fy,
            applied_mz,
            reaction_fx,
            reaction_fy,
            reaction_mz,
            tolerance: rel * f_scale,
            f_mag,
            m_mag,
            l_char,
            cond_rel_floor,
        }
    }

    fn check_node(&self, node: NodeHandle) -> Result<(), FemError> {
        if node.index() >= self.model.n_nodes() {
            return Err(FemError::InvalidNode(format!(
                "node handle {} is not valid for this result (max: {})",
                node.index(),
                self.model.n_nodes().saturating_sub(1)
            )));
        }
        Ok(())
    }

    fn check_member(&self, member: MemberHandle) -> Result<usize, FemError> {
        if member.index() >= self.model.n_members() {
            return Err(FemError::InvalidMember(format!(
                "member handle {} is not valid for this result (max: {})",
                member.index(),
                self.model.n_members().saturating_sub(1)
            )));
        }
        Ok(member.index())
    }
}

/// End-point coordinates of a member, or `None` if the index is out of range.
fn member_points(
    model: &BeamModel,
    member: usize,
) -> Option<(crate::geometry::Point, crate::geometry::Point)> {
    let el = model.elements.get(member)?;
    Some((
        model.nodes[el.node_i].point(),
        model.nodes[el.node_j].point(),
    ))
}

/// Characteristic length of the model: the largest absolute nodal coordinate.
///
/// The equilibrium moments are summed **about the origin**, so the length that
/// relates the force and moment scales must be measured from the origin too —
/// not a translation-invariant span. `0.0` for an empty model.
fn characteristic_length(model: &BeamModel) -> f64 {
    let mut l_char: f64 = 0.0;
    for node in &model.nodes {
        let p = node.point();
        l_char = l_char.max(p.x.abs()).max(p.y.abs());
    }
    l_char
}

/// Maximum element slenderness squared `λ² = L²·A/I` over all members.
///
/// This is a dimensionless element-level conditioning proxy for an
/// Euler–Bernoulli stiffness matrix: the forward error of a direct solve is
/// `O(λ²·ε)`, and the recovered reactions inherit that error, so equilibrium
/// residuals of a physically balanced frame can legitimately reach the same
/// relative magnitude. It is not a strict bound on the full assembled frame
/// stiffness matrix condition number.
///
/// Only elements with `I > 0` contribute to the maximum; elements with
/// non-positive `second_moment` are skipped (defensive guard, since
/// `BeamSection::new` does not validate `I`). Returns `0.0` for an empty model
/// or when no element has `I > 0`.
///
/// **Dimensionless and unit-invariant**: `L²·A/I` has units `m²·m²/m⁴ = 1`, and
/// a consistent change of length/area/inertia units multiplies numerator and
/// denominator by the same power, leaving the ratio unchanged. This is what
/// lets the conditioning floor feed a *relative* tolerance without breaking
/// unit invariance of the verdict.
fn max_element_slenderness_sq(model: &BeamModel) -> f64 {
    let mut lambda_sq: f64 = 0.0;
    for el in &model.elements {
        let p_i = model.nodes[el.node_i].point();
        let p_j = model.nodes[el.node_j].point();
        let l = el.length(p_i, p_j);
        let i = el.section.second_moment;
        if i > 0.0 {
            lambda_sq = lambda_sq.max(l * l * el.section.area / i);
        }
    }
    lambda_sq
}

// ---------------------------------------------------------------------------
// Single-source guarantee: the diagnostic reads the solver's condensed system
// ---------------------------------------------------------------------------
//
// These are in-crate tests on purpose: `tests/*.rs` are integration tests and
// cannot see `pub(crate)` items such as `BeamSolver::condense` /
// `FrameModel::classify`, so this guarantee is not testable from there.
#[cfg(test)]
mod reduced_system_single_source_tests {
    use super::*;
    use crate::fea::SparseMatrix;

    fn steel() -> Material {
        Material::new(200e9, 0.3, 7850.0, "Steel")
    }

    fn sec() -> BeamSection {
        BeamSection::new(5e-3, 2e-5)
    }

    /// The diagnostic must classify exactly the system the solver's own
    /// condensation produced: reading the live solver and the public API must
    /// agree on every structure in the battery.
    fn assert_agrees(f: &FrameModel, label: &str) -> Result<(), FemError> {
        let mut beam = BeamSolver::from_model(&f.inner)?;
        let from_solver = f.classify(beam.condense());
        assert_eq!(
            from_solver,
            f.diagnostic()?,
            "{label}: diagnostic disagrees with the solver's condensed system"
        );
        Ok(())
    }

    /// Two-column portal: `base1 - top1 - top2 - base2`, with the given supports
    /// on the two base nodes.
    fn portal(base_1: &[Dof], base_2: &[Dof]) -> Result<FrameModel, FemError> {
        let mut f = FrameModel::new();
        let b1 = f.add_node(0.0, 0.0)?;
        let t1 = f.add_node(0.0, 3.0)?;
        let t2 = f.add_node(4.0, 3.0)?;
        let b2 = f.add_node(4.0, 0.0)?;
        f.add_member(b1, t1, steel(), sec())?;
        f.add_member(t1, t2, steel(), sec())?;
        f.add_member(b2, t2, steel(), sec())?;
        for dof in base_1 {
            f.restrain(b1, *dof, 0.0)?;
        }
        for dof in base_2 {
            f.restrain(b2, *dof, 0.0)?;
        }
        Ok(f)
    }

    #[test]
    fn diagnostic_classifies_the_solver_condensed_system() -> Result<(), FemError> {
        // Completely free beam - three rigid-body modes.
        let mut free = FrameModel::new();
        let a = free.add_node(0.0, 0.0)?;
        let b = free.add_node(2.0, 0.0)?;
        free.add_member(a, b, steel(), sec())?;
        assert_agrees(&free, "free beam")?;

        // One DOF restrained - still under-constrained.
        let mut one = FrameModel::new();
        let a = one.add_node(0.0, 0.0)?;
        let b = one.add_node(2.0, 0.0)?;
        one.add_member(a, b, steel(), sec())?;
        one.restrain(a, Dof::Ux, 0.0)?;
        assert_agrees(&one, "one-DOF-restrained beam")?;

        // Stable cantilever.
        let mut cant = FrameModel::new();
        let base = cant.add_node(0.0, 0.0)?;
        let tip = cant.add_node(2.0, 0.0)?;
        cant.add_member(base, tip, steel(), sec())?;
        cant.fix(base)?;
        assert_agrees(&cant, "stable cantilever")?;

        // Portal with several support sets, stable and deficient.
        let fixed = portal(&[Dof::Ux, Dof::Uy, Dof::Rz], &[Dof::Ux, Dof::Uy, Dof::Rz])?;
        assert_agrees(&fixed, "portal, both bases fixed")?;
        let pinned = portal(&[Dof::Ux, Dof::Uy], &[Dof::Ux, Dof::Uy])?;
        assert_agrees(&pinned, "portal, both bases pinned")?;
        let roller = portal(&[Dof::Ux, Dof::Uy, Dof::Rz], &[Dof::Uy])?;
        assert_agrees(&roller, "portal, fixed base + roller")?;
        let mechanism = portal(&[Dof::Ux, Dof::Uy], &[])?;
        assert_agrees(&mechanism, "portal, single pin (mechanism)")?;

        Ok(())
    }

    #[test]
    fn diagnostic_uses_the_supplied_matrix_not_a_copy() -> Result<(), FemError> {
        let mut f = FrameModel::new();
        let base = f.add_node(0.0, 0.0)?;
        let tip = f.add_node(2.0, 0.0)?;
        f.add_member(base, tip, steel(), sec())?;
        f.fix(base)?;

        let mut beam = BeamSolver::from_model(&f.inner)?;
        let real = beam.condense().clone();
        let stable = f.classify(&real);
        assert_eq!(
            stable,
            StructuralDiagnostic::Stable,
            "control must be stable"
        );

        // Forge a reduced system with the first free DOF (tip `ux`) removed. If
        // `classify` reassembled its own matrix instead of reading its argument,
        // this forgery would have no effect at all.
        let n = real.k_ff().n;
        let mut forged_k = SparseMatrix::new(n);
        for i in 0..n {
            for j in 0..n {
                let v = real.k_ff().get(i, j);
                if i != 0 && j != 0 && v != 0.0 {
                    forged_k.add(i, j, v);
                }
            }
        }
        forged_k.compress();
        let forged = ReducedSystem::new(forged_k, real.free_to_global().to_vec());

        let verdict = f.classify(&forged);
        assert_ne!(
            verdict, stable,
            "classify must read the supplied matrix: zeroing a free DOF changed nothing"
        );
        // The public diagnostic still reads the untouched, real system.
        assert_eq!(f.diagnostic()?, stable);
        Ok(())
    }

    /// The failed-solve diagnostic must be driven by the solver's **retained**
    /// `K_ff`, not by a reassembly: the frame solve's error carries exactly the
    /// verdict that classifying the retained system produces.
    #[test]
    fn failed_solve_diagnosis_reads_the_solver_retained_system() -> Result<(), FemError> {
        // A free beam has the three rigid-body modes and cannot be solved.
        let mut f = FrameModel::new();
        let a = f.add_node(0.0, 0.0)?;
        let b = f.add_node(2.0, 0.0)?;
        f.add_member(a, b, steel(), sec())?;

        let expected = StructuralDiagnostic::RigidBodyMode {
            n_free: 6,
            rank: 3,
            rigid_modes: 3,
        };

        // (a) the frame solve fails as a `SolverError` that carries the verdict.
        let err = f.solve().expect_err("a free beam must not solve");
        match &err {
            FemError::SolverError { message, .. } => assert!(
                message.contains("structural diagnosis") && message.contains(&expected.to_string()),
                "expected the retained-system diagnosis in the error, got {message:?}"
            ),
            other => panic!("expected SolverError, got {other:?}"),
        }

        // (b) the verdict is exactly what the solver's retained reduced system
        // classifies to: run the identical solve path on a `BeamSolver` built the
        // same way, and classify the matrix that failed solve retained.
        let mut beam = BeamSolver::from_model(&f.inner)?;
        assert!(
            beam.solve_configured().is_err(),
            "the identical solve must also fail"
        );
        let retained = beam
            .reduced_system()
            .expect("a failed solve still retains the condensed system it factorised");
        assert_eq!(
            f.classify(retained),
            expected,
            "the diagnosis must come from the solver's retained K_ff"
        );
        Ok(())
    }

    /// A diagnosis that adds nothing (`Stable`) or is absent leaves the solver
    /// error byte-for-byte unchanged; only a mechanism annotates it. This covers
    /// the "failure before condensation leaves the error untouched" case: a
    /// missing diagnosis (`None`) is a no-op.
    #[test]
    fn diagnosis_only_annotates_mechanism_errors() {
        use crate::fea::solver::SolverError;
        let err = || FemError::from(SolverError::SingularMatrix("singular matrix".to_string()));
        let untouched = err().to_string();
        assert_eq!(
            with_structural_diagnosis(err(), None).to_string(),
            untouched
        );
        assert_eq!(
            with_structural_diagnosis(err(), Some(StructuralDiagnostic::Stable)).to_string(),
            untouched
        );
        let mechanism = StructuralDiagnostic::Mechanism { n_free: 4, rank: 3 };
        let annotated = with_structural_diagnosis(err(), Some(mechanism));
        assert!(
            matches!(annotated, FemError::SolverError { .. }),
            "the error variant must be preserved"
        );
        assert_eq!(
            annotated.to_string(),
            format!("{untouched}; structural diagnosis: {mechanism}")
        );
    }

    /// A model with **every** DOF restrained condenses to a 0x0 reduced system.
    /// The verdict is `Stable` (no free DOF means no mechanism) and the probe
    /// must not panic on the empty matrix / zero scale.
    #[test]
    fn fully_restrained_model_is_stable_and_does_not_panic() -> Result<(), FemError> {
        let mut f = FrameModel::new();
        let a = f.add_node(0.0, 0.0)?;
        let b = f.add_node(2.0, 0.0)?;
        f.add_member(a, b, steel(), sec())?;
        f.fix(a)?;
        f.fix(b)?;

        let mut beam = BeamSolver::from_model(&f.inner)?;
        let reduced = beam.condense();
        assert_eq!(reduced.k_ff().n, 0, "every DOF is restrained");
        assert!(reduced.free_to_global().is_empty());
        assert_eq!(f.classify(reduced), StructuralDiagnostic::Stable);

        // The public diagnostic agrees, and the fully prescribed solve is a
        // clean success - no panic, no mechanism claim.
        assert_eq!(f.diagnostic()?, StructuralDiagnostic::Stable);
        let result = f.solve()?;
        assert_eq!(result.displacement(a, Dof::Ux)?, 0.0);
        assert_eq!(result.displacement(b, Dof::Rz)?, 0.0);
        Ok(())
    }

    /// `condense()` is idempotent: repeated calls return the already-retained
    /// system (the same object, no re-condensation). `BeamSolver` has no mutator
    /// that can change the assembled system, so the cache cannot go stale.
    #[test]
    fn condense_is_idempotent_and_retained() -> Result<(), FemError> {
        let mut f = FrameModel::new();
        let base = f.add_node(0.0, 0.0)?;
        let tip = f.add_node(2.0, 0.0)?;
        f.add_member(base, tip, steel(), sec())?;
        f.fix(base)?;

        let mut beam = BeamSolver::from_model(&f.inner)?;
        assert!(beam.reduced_system().is_none(), "nothing condensed yet");

        let first = beam.condense() as *const ReducedSystem;
        let second = beam.condense() as *const ReducedSystem;
        assert_eq!(
            first, second,
            "repeated condense() must return the retained system, not rebuild it"
        );

        // A solve refreshes the retained system in place; after it, `condense()`
        // returns that retained object rather than re-condensing.
        beam.solve_configured()?;
        let after_k = beam
            .reduced_system()
            .expect("retained after a successful solve")
            .k_ff()
            .clone();
        let after_ptr = beam.reduced_system().unwrap() as *const ReducedSystem;
        assert_eq!(after_k.n, 3, "cantilever tip has 3 free DOFs");
        assert_eq!(
            beam.condense() as *const ReducedSystem,
            after_ptr,
            "condense() after a solve still returns the retained system"
        );

        // `set_solver` only chooses a backend; it cannot invalidate `K_ff`. The
        // retained content is unchanged across it.
        beam.set_solver(SolverSelection::Auto);
        let again = beam.condense();
        assert_eq!(again.k_ff().n, after_k.n);
        for i in 0..after_k.n {
            for j in 0..after_k.n {
                assert_eq!(
                    again.k_ff().get(i, j),
                    after_k.get(i, j),
                    "K_ff entry ({i},{j}) changed without a model change"
                );
            }
        }
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Equilibrium tolerance: relative, scale/unit invariant, never absolute
// ---------------------------------------------------------------------------
#[cfg(test)]
mod equilibrium_tolerance_tests {
    use super::*;

    /// Build a report with the given residuals and raw magnitudes. The
    /// conditioning floor is left at `0.0`, so the effective tolerance is
    /// exactly `EQUILIBRIUM_REL_TOL`: these tests exercise the scale/unit
    /// behaviour, not the conditioning relief (which has its own module below).
    fn report(
        fx_residual: f64,
        fy_residual: f64,
        mz_residual: f64,
        f_mag: f64,
        m_mag: f64,
        l_char: f64,
    ) -> EquilibriumReport {
        let (f_scale, _) = equilibrium_scales(f_mag, m_mag, l_char);
        EquilibriumReport {
            fx_residual,
            fy_residual,
            mz_residual,
            applied_fx: 0.0,
            applied_fy: 0.0,
            applied_mz: 0.0,
            reaction_fx: 0.0,
            reaction_fy: 0.0,
            reaction_mz: 0.0,
            tolerance: EQUILIBRIUM_REL_TOL * f_scale,
            f_mag,
            m_mag,
            l_char,
            cond_rel_floor: 0.0,
        }
    }

    #[test]
    fn force_and_moment_scales_are_unit_invariant() {
        // Same physical state: 2e6 N of force, 5e2 m lever arm, zero net moment.
        let (f_si, m_si) = equilibrium_scales(2.0e6, 0.0, 5.0e2);
        assert_eq!(f_si, 2.0e6);
        assert_eq!(m_si, 1.0e9);
        // kN / mm: force 2e3 kN, lever arm 5e5 mm.
        let (f_kmm, m_kmm) = equilibrium_scales(2.0e3, 0.0, 5.0e5);
        assert_eq!(f_kmm, 2.0e3);
        // 1e9 kN·mm == 1e9 N·m: the moment scale is the same physical quantity.
        assert_eq!(m_kmm, m_si);
    }

    #[test]
    fn moment_scale_is_non_degenerate_with_zero_applied_moment() {
        // Forces present but `applied_mz == 0`: the moment scale must not
        // collapse to a constant (the old `|applied_mz|`-only definition did).
        let (_, m_scale) = equilibrium_scales(2.0e6, 0.0, 5.0e2);
        assert_eq!(m_scale, 2.0e6 * 5.0e2);
        assert!(m_scale > 0.0);
    }

    #[test]
    fn scales_vanish_only_when_nothing_is_present() {
        assert_eq!(equilibrium_scales(0.0, 0.0, 5.0e2), (0.0, 0.0));
        assert_eq!(equilibrium_scales(0.0, 0.0, 0.0), (0.0, 0.0));
    }

    #[test]
    fn unloaded_report_is_balanced_only_with_exact_zero_residual() {
        assert!(report(0.0, 0.0, 0.0, 0.0, 0.0, 5.0e2).is_balanced());
        assert!(!report(0.0, 0.0, f64::MIN_POSITIVE, 0.0, 0.0, 5.0e2).is_balanced());
        assert!(!report(f64::MIN_POSITIVE, 0.0, 0.0, 0.0, 0.0, 5.0e2).is_balanced());
    }

    #[test]
    fn corrupted_reaction_is_still_rejected() {
        // No over-relaxation: the relative bound must still reject a genuine
        // imbalance, while accepting round-off.
        let (f_scale, m_scale) = equilibrium_scales(1.0e6, 0.0, 5.0e2);
        assert!(
            report(
                1e-15 * f_scale,
                1e-15 * f_scale,
                1e-15 * m_scale,
                1.0e6,
                0.0,
                5.0e2
            )
            .is_balanced()
        );
        assert!(
            !report(
                1e-3 * f_scale,
                1e-3 * f_scale,
                1e-3 * m_scale,
                1.0e6,
                0.0,
                5.0e2
            )
            .is_balanced()
        );
    }

    /// Build a report with an explicit conditioning floor, so the anti-masking
    /// test can exercise `cond_rel_floor > 0` directly.
    fn report_with_cond(
        fx_residual: f64,
        fy_residual: f64,
        mz_residual: f64,
        f_mag: f64,
        m_mag: f64,
        l_char: f64,
        cond_rel_floor: f64,
    ) -> EquilibriumReport {
        let (f_scale, _) = equilibrium_scales(f_mag, m_mag, l_char);
        let rel = EQUILIBRIUM_REL_TOL.max(cond_rel_floor);
        EquilibriumReport {
            fx_residual,
            fy_residual,
            mz_residual,
            applied_fx: 0.0,
            applied_fy: 0.0,
            applied_mz: 0.0,
            reaction_fx: 0.0,
            reaction_fy: 0.0,
            reaction_mz: 0.0,
            tolerance: rel * f_scale,
            f_mag,
            m_mag,
            l_char,
            cond_rel_floor,
        }
    }

    #[test]
    fn conditioning_floor_accepts_roundoff_rejects_genuine_imbalance() {
        // A slender frame: λ² ≈ 2.5e14, so the conditioning floor dominates.
        // cond_floor = 1e-2 · 2.5e14 · ε ≈ 5.55e-4.
        let lambda_sq = 2.5e14;
        let cond_floor = EQUILIBRIUM_COND_FACTOR * lambda_sq * f64::EPSILON;
        assert!(
            cond_floor > EQUILIBRIUM_REL_TOL,
            "this test needs a floor above the base tolerance"
        );

        let (f_scale, m_scale) = equilibrium_scales(1.0e12, 0.0, 5.0e5);

        // (a) Residual at 10% of the conditioning floor: pure round-off,
        //     must be accepted.
        assert!(
            report_with_cond(
                0.1 * cond_floor * f_scale,
                0.1 * cond_floor * f_scale,
                0.1 * cond_floor * m_scale,
                1.0e12,
                0.0,
                5.0e5,
                cond_floor
            )
            .is_balanced(),
            "round-off below the conditioning floor must be accepted"
        );

        // (b) Residual at 10× the conditioning floor: a genuine imbalance,
        //     must be rejected — the floor must not mask it.
        assert!(
            !report_with_cond(
                10.0 * cond_floor * f_scale,
                10.0 * cond_floor * f_scale,
                10.0 * cond_floor * m_scale,
                1.0e12,
                0.0,
                5.0e5,
                cond_floor
            )
            .is_balanced(),
            "imbalance above the conditioning floor must be rejected"
        );
    }

    #[test]
    fn conditioning_floor_is_dimensionless_and_unit_invariant() {
        // λ² = L²·A/I is dimensionless: the same physical element expressed in
        // SI (m, m², m⁴) and kN/mm (mm, mm², mm⁴) gives the same λ².
        let l_si = 1.0e6_f64;
        let a_si = 5.0e-3_f64;
        let i_si = 2.0e-5_f64;
        let lambda_sq_si = l_si * l_si * a_si / i_si;

        let l_kmm = 1.0e9_f64; // 1e6 m = 1e9 mm
        let a_kmm = 5.0e3_f64; // 5e-3 m² = 5e3 mm²
        let i_kmm = 2.0e7_f64; // 2e-5 m⁴ = 2e7 mm⁴
        let lambda_sq_kmm = l_kmm * l_kmm * a_kmm / i_kmm;

        // The two values differ only by round-off in the multiplications.
        let avg = 0.5 * (lambda_sq_si + lambda_sq_kmm);
        assert!(
            (lambda_sq_si - lambda_sq_kmm).abs() <= 10.0 * f64::EPSILON * avg,
            "λ² must be unit-invariant (SI={}, kN/mm={})",
            lambda_sq_si,
            lambda_sq_kmm
        );
    }
}