Step 7: newton-iteration-log-writer

읽어야 할 파일

AGENTS.md
docs/ARCHITECTURE.md
docs/nonlinear-static-newton-raphson/io.md
docs/nonlinear-static-newton-raphson/formulation.md
docs/nonlinear-static-newton-raphson/implementation-plan.md
Step 0 files: include/fesa/app/output_paths.h, src/fesa/app/output_paths.cpp, include/fesa/analysis/analysis.h
Step 5 files: include/fesa/analysis/nonlinear_static_control.h

이전 Step 전제

Step 0 gives app-owned log path and lease lifetime. Step 5 defines convergence-channel data that log records consume.

소유 파일

Create: include/fesa/analysis/newton_iteration_log.h
Create: src/fesa/analysis/newton_iteration_log.cpp
Create: tests/unit/analysis/newton_iteration_log_test.cpp
Modify: src/fesa/CMakeLists.txt
Modify: tests/CMakeLists.txt

인터페이스

namespace fesa {

enum class NewtonIterationStage {
  kEntered,
  kKinematicsEvaluated,
  kInternalAssembled,
  kExternalAssembled,
  kSolvedCorrection,
  kConvergenceEvaluated,
  kAccepted,
  kFailed
};

struct NewtonIterationFailure {
  bool present;
  NewtonIterationStage stage;
  std::string diagnostic_code;
  std::string reason;
};

struct NewtonIterationLogRecord {
  std::string step_name;
  std::uint32_t increment_index;
  double load_factor;
  std::uint32_t iteration;
  NewtonIterationStage last_completed_stage;
  NewtonIterationFailure failure;
  std::string transition;
  std::string outcome;
  std::string diagnostic_code;
  NewtonChannelDecision force_residual;
  NewtonChannelDecision moment_residual;
  NewtonChannelDecision translation_correction;
  NewtonChannelDecision rotation_correction;
  bool combined_passed;
};

class NewtonIterationLogWriter {
 public:
  Status Open(const std::filesystem::path& log_path);
  Status Write(const NewtonIterationLogRecord& record);
  Status Flush();
  Status Close();
};

}  // namespace fesa

The serializer, not callers, owns the exact 39 labels and fixed order from io.md. For evaluated convergence channels it serializes only relative or zero-scale branch labels from NewtonConvergenceBranch. For unevaluated typed fields it writes not-evaluated(reason) using NewtonIterationFailure::reason. Callers cannot inject arbitrary fields.

RED

Add tests first.

NSNR-LOG-001: a complete Newton iteration writes exactly one LF-terminated line.
NSNR-LOG-002: line is UTF-8 without BOM, no header, no trailer.
NSNR-LOG-003: line has exactly 39 TAB-separated label=value fields in approved order.
NSNR-LOG-004: finite numeric values round-trip without locale dependence.
NSNR-LOG-005: each convergence channel serializes identity, numerator_norm, denominator_scale, branch, threshold, threshold_unit, and pass from NewtonChannelDecision.
NSNR-LOG-006: evaluated empty free-channel decisions serialize numerator_norm=0, denominator_scale=0, threshold 1.0e-3, the channel-specific zero-scale threshold_unit, and branch zero-scale; no other branch label appears.
NSNR-LOG-007: combined pass, transition, outcome, failure stage, and diagnostic code are serialized from explicit record fields.
NSNR-LOG-008: early failure fields after the failed stage use not-evaluated(reason).
NSNR-LOG-009: embedded tab, LF, CR, and backslash are escaped deterministically.
NSNR-LOG-010: write/flush/close failure returns log-output-failure and prevents success classification.
NSNR-LOG-011: non-Newton controlled failure path can leave a zero-byte log owned by app lifecycle.

Run:

cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R "NewtonIterationLog" --output-on-failure

Expected: new tests fail. Unexpected pass stops.

GREEN

Implement a small log writer with explicit open/write/flush/close state, serializer-owned 39-field order, deterministic escaping, finite numeric formatting, relative/zero-scale convergence branch mapping, typed not-evaluated(reason) substitution, and structured Status failures.

VERIFY

cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
  "-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
  "-DMKL_DIR=$mklDir" `
  "-DTBB_DIR=$tbbDir" `
  "-DHDF5_DIR=$hdf5Dir"
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R "NewtonIterationLog" --output-on-failure
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

Recheck .harness/config.json before default commands.

상태 기록

Update only Step 7 status and one-line payload. Executor owns timestamps, commits, retry, and advancement.

금지사항

Do not duplicate per-iteration log lines to stderr. 이유: approved log is file-only.
Do not accept arbitrary caller-provided field vectors. 이유: io.md requires an exact fixed schema and order.
Do not write HDF5 trial history. 이유: log is diagnostic and HDF5 stores accepted frames only.
Do not continue after log write/flush/close failure. 이유: log failure blocks result commit.

5.0 KiB Raw Blame History