baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(nonlinear-static-newton-raphson): step 11 - equilibrium-projection-and-reference-gate

Browse Source
This commit is contained in:
KOKO\Mimi
2026-08-28 09:22:33 +09:00
parent 65b56b1755
commit 6dbf1b2bcf
30 changed files with 13122 additions and 728 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/nonlinear-static-newton-raphson/requirements.md
+37 -33
View File
@@ -3,11 +3,11 @@
## 1. Metadata
- feature_id: `nonlinear-static-newton-raphson`
- title: `Nonlinear Static Analysis Using Newton–Raphson`
- status: `approved`
- status: `draft`
- owner_agent: `requirement-agent`
- date: `2026-08-22`
- approved_by: user
- approval_date: `2026-08-23`
- date: `2026-08-27`
- approved_by: pending user re-approval
- approval_date: pending
- authoritative_scope: materially linear, geometrically nonlinear `S4/S4R -> FESA-MITC4`
- independence: FESA는 독립 solver이며 Abaqus 또는 Midas의 내부 알고리즘 동등성을 주장하지 않는다.
- unit_policy: `.inp` 단위계를 추론하거나 변환하지 않고 사용자가 일관되게 제공한 단위계를 보존한다.
@@ -26,7 +26,7 @@ FESA는 하나의 지원 nonlinear static step을 scalar load factor로 증가
- factor-1 absolute prescribed `*BOUNDARY` targets와 four-value nonlinear `*STATIC`
- four-channel residual/correction convergence, maximum 100 iterations, no line search
- separate trial state, atomic commit/rollback, accepted-frame HDF5와 per-iteration text log
- deterministic assembly, iteration, frame, result, diagnostic order와 stored-reference verification
- deterministic assembly, iteration, frame, result, diagnostic order와 factor-one global reaction/equilibrium 및 stored-reference verification
## 4. Out Of Scope
- material nonlinearity, nonlinear material history, combined material/geometric nonlinearity
@@ -138,16 +138,16 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
status: approved
- id: FESA-REQ-NSNR-069
statement: "The FESA solver shall evaluate translational-force and rotational-moment free-residual convergence with channel-separated infinity-norm gates."
statement: "The FESA solver shall evaluate translational-force and rotational-moment free-residual convergence with channel-separated infinity-norm gates selected by each matching external residual-channel scale."
category: numerical
rationale: "Force and moment dimensions require separate scales."
source: user
priority: must
verification_method: test
acceptance_criteria: "For a nonzero matching-channel denominator max(||internal||inf, ||external||inf), the same-trial residual ratio passes iff <=1e-2; an exact-zero denominator instead passes iff its numerator is <=1e-3 model-consistent force or <=1e-3 model-consistent force-length, respectively."
tolerance: "Relative 1e-2 dimensionless; zero-scale absolute 1e-3 force and 1e-3 force-length."
acceptance_criteria: "For each residual channel, a nonzero matching external-channel scale retains denominator max(||internal||inf, ||external||inf), and the same-trial residual ratio passes iff <=1e-2; an exact-zero matching external-channel scale instead applies the typed absolute gate, which passes iff its numerator is <=1e-3 model-consistent force or <=1e-3 model-consistent force-length, respectively."
tolerance: "Relative 1e-2 dimensionless for nonzero matching external-channel scale; exact-zero matching external-channel absolute 1e-3 force and 1e-3 force-length."
trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
status: approved
status: draft
- id: FESA-REQ-NSNR-070
statement: "The FESA solver shall evaluate translational and rotational free-correction convergence with channel-separated infinity-norm gates."
category: numerical
@@ -248,14 +248,14 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
trace_to: {parent_need: "NEED-NSNR-003", downstream_agents: ["Formulation Agent", "Numerical Review Agent", "Implementation Planning Agent"]}
status: approved
- id: FESA-REQ-NSNR-019
statement: "The FESA solver shall preserve stable source identity and stable assembly order and shall derive free residual and constrained reaction from the complete assembled equilibrium at the same state."
statement: "The FESA solver shall preserve stable source identity and stable assembly order and shall keep the accepted free residual, constrained reaction resultant, and global applied-plus-reaction balance error as distinct equilibrium quantities derived at the same accepted state."
category: physics
rationale: "Equilibrium evidence must remain traceable to source entities and DOFs."
rationale: "Reaction and equilibrium evidence must remain traceable without treating physically distinct projections as interchangeable."
source: docs
priority: must
verification_method: test
acceptance_criteria: "Input instance/label/component maps deterministically through assembly, state, diagnostic, result, and comparison; full residual at a trial or accepted state yields free-equilibrium evidence and constrained reactions."
tolerance: "Source/component identity and discrete order exact; equilibrium uses approved numerical tolerances."
acceptance_criteria: "Input instance/label/component maps deterministically through assembly, state, diagnostic, result, and comparison; accepted free entries remain free-equilibrium evidence, constrained entries form physical reactions, and the constrained-reaction resultant remains distinct from the global applied-plus-reaction balance error. Blocking factor-one equilibrium quantities are global applied-plus-reaction force [3] and moment [3] balance errors plus accepted free residual. Every global moment is about global origin [0,0,0] and uses current force arms plus spatial physical nodal moments."
tolerance: "Source/component, quantity identity, origin, and discrete order exact; equilibrium and reference values use their separately approved numerical tolerances."
trace_to: {parent_need: "NEED-NSNR-002, NEED-NSNR-004", downstream_agents: ["Formulation Agent", "Numerical Review Agent", "I/O Definition Agent"]}
status: approved
- id: FESA-REQ-NSNR-020
@@ -314,25 +314,25 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
trace_to: {parent_need: "NEED-NSNR-003, NEED-NSNR-004", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
status: approved
- id: FESA-REQ-NSNR-030
statement: "The FESA solver shall pass an approved verification portfolio covering the materially linear small-displacement limit, tangent consistency, equilibrium/reaction, symmetry or objectivity, and commit/rollback behavior."
statement: "The FESA solver shall pass an approved verification portfolio covering the materially linear small-displacement limit, tangent consistency, factor-one global applied-plus-reaction balance and accepted free residual, symmetry or objectivity, and commit/rollback behavior."
category: verification
rationale: "Convergence alone does not establish nonlinear solver correctness."
source: docs
priority: must
verification_method: analysis
acceptance_criteria: "Numerical Review defines blocking cases and quantities for every listed category, and implementation passes each approved analytical, invariant, physics, or comparison gate."
tolerance: "Case-specific tolerances are owned by Numerical Review; existing linear-limit tolerance remains unchanged."
acceptance_criteria: "Numerical Review defines blocking cases and quantities for every listed category, and implementation passes each approved analytical, invariant, physics, or comparison gate. Reaction/equilibrium acceptance separately blocks on factor-one global applied-plus-reaction force [3] and moment [3] balance errors and accepted free-DOF residual evidence; constrained-reaction resultants retain a distinct identity, and local nodal reaction distribution does not decide the blocking verdict."
tolerance: "Case-specific invariant tolerances are owned by Numerical Review; external comparisons use docs/TOLERANCE.md; existing linear-limit tolerance remains unchanged."
trace_to: {parent_need: "NEED-NSNR-004", downstream_agents: ["Research Agent", "Formulation Agent", "Numerical Review Agent"]}
status: approved
- id: FESA-REQ-NSNR-034
statement: "The FESA solver shall compare only approved accepted-state quantities against stored reference artifacts using stable source/component matching and the common docs/TOLERANCE.md policy."
statement: "The FESA solver shall compare only approved accepted-state quantities against stored reference artifacts using stable source/component matching, the approved blocking/warning/review disposition, and the common docs/TOLERANCE.md policy."
category: verification
rationale: "Reference acceptance must be deterministic and independent of solver execution."
source: docs
priority: must
verification_method: reference-comparison
acceptance_criteria: "Numerical Review selects the exact existing input and required CSV quantities; precheck rejects missing, extra, duplicate, or nonfinite required rows before blocking/warning family comparison, without averaging or row-order matching."
tolerance: "docs/TOLERANCE.md family-scale policy; exact artifacts and families are a Numerical Review-owned readiness gap."
acceptance_criteria: "Numerical Review selects the exact existing input and required CSV quantities; precheck rejects missing, extra, duplicate, or nonfinite required rows before numerical comparison, without averaging, collapse, row-order matching, zero clamp, or reference repair. U1/U2/U3 remain blocking and UR1/UR2/UR3 remain warning-only. Local nodal RF1/RF2/RF3 and physical spatial RM1/RM2 retain deterministic source-key/schema/finite/inventory/error reporting but are review-only and never change the blocking verdict; local RM3 and stress remain excluded from numerical comparison."
tolerance: "docs/TOLERANCE.md family-scale policy for external blocking, warning-only, and review-only error reporting; exact artifact roles, local review projection, family membership, and row schema are a Numerical Review-owned readiness gap."
trace_to: {parent_need: "NEED-NSNR-004", downstream_agents: ["Numerical Review Agent", "I/O Definition Agent"]}
status: approved
```
@@ -341,7 +341,10 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
| quantity | dimension / coordinates | role |
| --- | --- | --- |
| nodal displacement and committed rotation/director state | length and dimensionless rotation; global | accepted-state kinematics and rollback |
| full residual and constrained reaction | force or force-length; global DOF | equilibrium and reaction evidence |
| accepted free-DOF residual | force or force-length; global DOF | blocking accepted-state equilibrium evidence |
| local nodal `RF1/RF2/RF3`, physical spatial `RM1/RM2` | force or force-length; global | deterministic review-only/nonblocking distribution evidence; `RM3` excluded |
| constrained-reaction resultant force `[3]` and moment `[3]` | force and force-length; global; moment about `[0,0,0]` with current arms and spatial physical moments | distinct reaction summary; not interchangeable with global balance error |
| applied-plus-reaction balance error force `[3]` and moment `[3]` | force and force-length; global; same origin/arm/moment convention | blocking factor-one reaction/equilibrium evidence |
| MITC4 internal force, stress and strain | model-consistent dimensions; approved element frame/configuration | formulation, physics and reference verification |
| scalar load factor and accepted frame identity | dimensionless | path, commit and output ordering |
| four convergence channels | typed as NSNR-069/070 | internal iteration acceptance only |
@@ -349,13 +352,14 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
## 10. Tolerance Policy
- `.inp` values remain in the user's consistent unit system; FESA performs no unit inference or conversion.
- Only nonzero-scale convergence ratios are dimensionless and pass with `<=1e-2`.
- Exact-zero residual thresholds are `1e-3` force and `1e-3` force-length; correction thresholds are `1e-3` length and `1e-3` dimensionless rotation. Equal literals do not merge their dimensions.
- External comparisons use `docs/TOLERANCE.md`; internal invariant, tangent, endpoint-arithmetic and physics tolerances are fixed by Numerical Review before implementation.
- Residual ratios with nonzero matching external-channel scale and correction ratios with nonzero current-trial incremental-solution denominator are dimensionless and pass with `<=1e-2`.
- Exact-zero matching external-channel residual thresholds are `1e-3` force and `1e-3` force-length; exact-zero correction-denominator thresholds are `1e-3` length and `1e-3` dimensionless rotation. Equal literals do not merge their dimensions.
- External blocking, warning-only, and review-only error reporting use `docs/TOLERANCE.md` without changing their verdict disposition; internal invariant, tangent, endpoint-arithmetic, free-residual and global-balance tolerances are fixed by Numerical Review before implementation.
## 11. Reference Case Requirements
- The current Stage-1 gap is selection of exact stored nonlinear input and only the CSV quantities required for acceptance.
- Numerical Review owns artifact readiness, blocking/warning families, source/component identity and HDF5 projection; this gap does not require another Stage-1 user question.
- Stored nonlinear candidates use exact read-only input/displacement pairs `reference/shellNL/shellNL.inp` with `reference/shellNL/shellNL displacements.csv`, and `reference/shellNL-meshfine/shellNL-meshfine.inp` with `reference/shellNL-meshfine/shellNL-meshfine displacements.csv`. Exact local-reaction review artifacts are `reference/shellNL/shellNL reactions.csv` and `reference/shellNL-meshfine/shellNL-meshfine reactions.csv`; they are not missing-required blocking artifacts. The existing linear-limit pair is `reference/shell/shell.inp` and `reference/shell/shell displacements.csv`.
- Numerical Review shall fix which exact nonlinear candidate case or cases are blocking versus diagnostic, the factor-one HDF5 projection, required source rows/components and comparison families, and the internal tolerances for global balance/free-residual gates. `U1/U2/U3` are blocking, `UR1/UR2/UR3` are warning-only, local nodal RF/RM rows are review-only, and `RM3` and stress have no numerical comparison projection.
- All selected local review rows retain deterministic identity, schema, finite-value, inventory, and error reporting even though they cannot fail the blocking verdict. A physical global resultant sum is not a substitute identity for those local rows, and no row is averaged, collapsed, omitted, zero-clamped, or repaired.
- Agents do not run Abaqus, Nastran or another reference solver and do not create, rename, repair or normalize stored reference artifacts.
## 12. Requirement Verification Matrix
@@ -367,7 +371,7 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
| `NSNR-074` | physics | user | must | analysis | finite committed/trial triad/director state and rollback | invariant tolerance downstream | Formulation; Numerical Review | approved |
| `NSNR-006` | numerical | user | must | test | same-trial residual/tangent and fresh factorization/solve | identity/order exact | Formulation; Numerical Review; Planning | approved |
| `NSNR-007` | numerical | user | must | test | all four free-DOF gates pass; constrained residual is reaction | NSNR-069/070 | Numerical Review; Planning | approved |
| `NSNR-069` | numerical | user | must | test | force/moment residual relative or typed zero-scale gates | `1e-2`; typed `1e-3` | Numerical Review; Planning | approved |
| `NSNR-069` | numerical | user | must | test | force/moment residual relative gate for nonzero external scale; typed absolute gate for exact-zero external scale | `1e-2`; typed `1e-3` | Numerical Review; Planning | draft |
| `NSNR-070` | numerical | user | must | test | translation/rotation correction relative or typed zero-scale gates | `1e-2`; typed `1e-3` | Numerical Review; Planning | approved |
| `NSNR-008` | numerical | user | must | test | finite data, iterations 1..100, pass at 100 allowed | predicates/count exact | Numerical Review; Planning | approved |
| `NSNR-014` | constraint | user | must | test | unchanged full correction; no line search/fallback/energy gate | identity exact | Numerical Review; Planning | approved |
@@ -377,21 +381,21 @@ Exact Total Lagrangian shell equations, strain/stress measures, rotation map det
| `NSNR-063` | physics | user | must | test | absolute factor-one BC target and separate correction | path/source exact | Formulation; Numerical Review | approved |
| `NSNR-016` | input | user | must | test | four-value STATIC mapping and validation | endpoint exact | I/O; Planning | approved |
| `NSNR-011` | functional | user | must | test | separate trial, atomic commit, prior-state preservation | state exact | Formulation; Numerical Review; Planning | approved |
| `NSNR-019` | physics | docs | must | test | stable source/assembly and full-equilibrium residual/reaction | identity/order exact | Formulation; Numerical Review; I/O | approved |
| `NSNR-019` | physics | docs | must | test | distinct free residual, constrained-reaction resultants and applied+reaction balance; current-arm/spatial-moment semantics | quantity/origin/identity/order exact | Formulation; Numerical Review; I/O | approved |
| `NSNR-020` | input | docs | must | test | unsupported meaning fails closed | inventory exact | I/O; Planning | approved |
| `NSNR-021` | output | user | must | test | accepted commit/frame bijection and failure-safe HDF5 final | identity exact | Numerical Review; I/O; Planning | approved |
| `NSNR-024` | output | user | must | test | one ordered diagnostic summary per entered iteration and persistent live log | semantic identity exact | I/O; Planning | approved |
| `NSNR-083` | output | user | must | test | repository names; every literal --output form unrecognized with pre-input/pre-Analysis/pre-output exit 2 and no alias/deprecation; asymmetric lifecycle; linear regression | public identity/precedence exact | I/O; Planning; Numerical Review | approved |
| `NSNR-026` | constraint | docs | must | test | deterministic factor/iteration/assembly/frame/result/log order | discrete order exact | Numerical Review; Planning | approved |
| `NSNR-030` | verification | docs | must | analysis | blocking small-limit/tangent/physics/rollback portfolio | case-specific downstream | Research; Formulation; Numerical Review | approved |
| `NSNR-034` | verification | docs | must | reference-comparison | stored artifacts, deterministic matching and precheck | docs/TOLERANCE.md | Numerical Review; I/O | approved |
| `NSNR-030` | verification | docs | must | analysis | blocking small-limit/tangent/global applied+reaction balance/free-residual/physics/rollback portfolio | case-specific downstream; external policy unchanged | Research; Formulation; Numerical Review | approved |
| `NSNR-034` | verification | docs | must | reference-comparison | U blocking, UR warning-only, local RF/RM review-only, exact matching/precheck | docs/TOLERANCE.md | Numerical Review; I/O | approved |
## 13. Open Questions
없음. Specialist gaps are owned by downstream stages and are escalated only if they would change approved scope, physics, tolerance, authoritative output or public compatibility.
## 14. Downstream Handoff
- Research/Formulation: exact Total Lagrangian MITC4 equations, strain/stress measures, rotation map/side/frame, drilling and consistent derivatives.
- Numerical Review: endpoint arithmetic, tangent/objectivity/state-invariant checks, benchmark portfolio, performance adequacy and exact reference artifacts/quantities.
- I/O Definition: HDF5 schema/projection/chunking/factor-0 handling, log representation/failure presentation and path/collision conventions.
- Implementation Planning: backend adapters, output ownership primitive, candidate filename, performance targets and requirement-traced TDD plan.
- Research/Formulation: exact Total Lagrangian MITC4 equations, strain/stress measures, rotation map/side/frame, drilling and consistent derivatives; Formulation propagates NSNR-069's exact-zero matching external-channel typed absolute branch and retained nonzero external-scale relative denominator.
- Numerical Review: verify the revised NSNR-069 branch and unchanged thresholds/four-channel AND, endpoint arithmetic, tangent/objectivity/state-invariant checks, benchmark portfolio and performance adequacy. Fix exact coarse/fine reference roles, local review projection/families, and factor-one global balance/free-residual tolerances while preserving local RF/RM review-only, `RM3` exclusion, displacement/rotation disposition, exact prechecks, immutable artifacts and common external tolerance.
- I/O Definition: HDF5 schema/projection/chunking/factor-0 handling, log representation/failure presentation and path/collision conventions. Audit and keep separately identifiable `(a)` global applied-plus-reaction balance error, `(b)` constrained-reaction resultant and `(c)` accepted free residual; global moments use current positions and spatial physical nodal moments about `[0,0,0]`, including supported nonzero prescribed translation/rotation cases.
- Implementation Planning: backend adapters, output ownership primitive, candidate filename, performance targets and requirement-traced TDD plan. Stage 6 must test the three equilibrium identities separately and must not reuse one implementation dataset as another without proving its approved projection semantics.
- Coordinator: escalate only a downstream proposal that changes the approved scope, physics, convergence tolerance, authoritative-result meaning or public output contract; do not advance the workflow on this document alone.