KOKO\Mimi
131 lines
5.0 KiB
Markdown
131 lines
5.0 KiB
Markdown
# Step 14: Runtime Element and Factory
|
||
|
||
## 담당 역할과 필수 스킬
|
||
|
||
- 담당 역할: `implementation-agent`
|
||
- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
|
||
- 이 Step만 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`로 수행한다.
|
||
|
||
## 읽어야 할 파일
|
||
|
||
- `/AGENTS.md`
|
||
- `/docs/CODINGSTYLE.md`
|
||
- `/docs/ARCHITECTURE.md`
|
||
- `/docs/ADR.md`
|
||
- `/docs/linear-static-3d-euler-beam/formulation.md`
|
||
- `/docs/linear-static-mitc4-shell/formulation.md`
|
||
- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
|
||
- Step 12 material/property hierarchy files
|
||
- Step 13 element definition and Domain files
|
||
- `/include/fesa/elements/euler_beam_3d.h`, `/src/fesa/elements/euler_beam_3d.cpp`
|
||
- `/include/fesa/elements/mitc4_shell.h`, `/src/fesa/elements/mitc4_shell.cpp`
|
||
- element/model/result record tests
|
||
- `/src/fesa/CMakeLists.txt`, `/tests/CMakeLists.txt`
|
||
- `/phases/cpp-object-oriented-modular-refactoring/index.json`
|
||
- `/phases/cpp-object-oriented-modular-refactoring/step14.md`
|
||
|
||
## 작업
|
||
|
||
Requirement `R-ELEMENT-001`의 numerical runtime boundary를 구현한다.
|
||
|
||
1. `/tests/unit/elements/element_factory_test.cpp`를 먼저 추가한다. `C-ELEMENT-001` covers
|
||
base-pointer virtual destruction, B33 and MITC4 factory success, stable DOF layout, stiffness
|
||
and recovery through base, unknown/mismatched property/material/null rejection.
|
||
2. Missing `element.h` and `element_factory.h` cause RED compile failure.
|
||
3. Create `/include/fesa/elements/element.h`,
|
||
`/include/fesa/elements/element_factory.h`, and
|
||
`/src/fesa/elements/element_factory.cpp`; register the source and factory test in CMake.
|
||
4. Candidate interfaces:
|
||
|
||
```cpp
|
||
struct ElementDofLayout {
|
||
SourceEntityId source_id;
|
||
std::vector<EntityIndex> node_indices;
|
||
std::vector<DofComponent> components_per_node;
|
||
};
|
||
|
||
struct ElementStiffnessContribution {
|
||
ElementDofLayout layout;
|
||
Matrix values;
|
||
};
|
||
|
||
struct BeamElementResultRows {
|
||
std::vector<EndpointResultRow> endpoint_rows;
|
||
std::vector<GaussResultRow> gauss_rows;
|
||
std::vector<StressS11Row> stress_rows;
|
||
};
|
||
|
||
struct ShellElementResultRows {
|
||
std::vector<ShellResultRow> rows;
|
||
double physical_strain_energy;
|
||
};
|
||
|
||
using ElementResultPayload =
|
||
std::variant<BeamElementResultRows, ShellElementResultRows>;
|
||
|
||
struct ElementResultBundle {
|
||
SourceEntityId source_id;
|
||
ElementResultPayload payload;
|
||
};
|
||
|
||
class Element {
|
||
public:
|
||
virtual ~Element() = default;
|
||
virtual const ElementDofLayout& DofLayout() const noexcept = 0;
|
||
virtual Result<ElementStiffnessContribution> ComputeStiffness() const = 0;
|
||
virtual Result<ElementResultBundle> Recover(
|
||
const Vector& full_displacement) const = 0;
|
||
};
|
||
|
||
using ElementView = std::vector<std::reference_wrapper<const Element>>;
|
||
|
||
class ElementFactory {
|
||
public:
|
||
Result<std::unique_ptr<Element>> Create(
|
||
const ElementDefinition& definition,
|
||
const Domain& domain) const;
|
||
};
|
||
```
|
||
|
||
5. The linear-static candidate owns `std::vector<std::unique_ptr<Element>>` and builds an
|
||
`ElementView` whose lifetime is bounded by that owner. Carrier type locations may be adjusted
|
||
to avoid circular public dependencies, but semantics and names must stay consistent for
|
||
Steps 15–17.
|
||
6. Factory centralizes explicit definition/property/material kind compatibility, bounds checks,
|
||
and structured diagnostic. It may use a checked kind discriminator and concrete access after
|
||
validation; downstream consumers must not downcast.
|
||
7. Existing B33/MITC4 numerical kernels implement `Element` without changing formulation or adding
|
||
fields meaningless to the other element.
|
||
|
||
## Acceptance Criteria
|
||
|
||
```powershell
|
||
cmake --build .harness/build --config Debug --target fesa_unit_tests
|
||
ctest --test-dir .harness/build -C Debug `
|
||
-R "ElementFactory|EulerBeam3D|Mitc4Shell" --output-on-failure
|
||
rg -n "dynamic_cast" src/fesa include/fesa
|
||
& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror `
|
||
include/fesa/elements/element.h include/fesa/elements/element_factory.h `
|
||
src/fesa/elements/element_factory.cpp tests/unit/elements/element_factory_test.cpp
|
||
cmake --build .harness/build --config Debug
|
||
ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||
```
|
||
|
||
The downcast scan must show no newly scattered consumer downcasts. If the centralized factory uses
|
||
a checked cast, document the preceding kind validation and keep it in the factory only.
|
||
|
||
## 검증 및 상태 갱신
|
||
|
||
- RED, success/rejection cases, base stiffness/recovery, downcast scan and full CTest를 summary에 기록한다.
|
||
- Formulation or result identity changes are `error`.
|
||
- 성공 시 현재 Step만 `completed`로 갱신한다.
|
||
- timestamp, retry, commit, advancement는 Executor 소유다.
|
||
|
||
## 금지사항
|
||
|
||
- Semantic definition and runtime kernel을 one class로 합치지 마라.
|
||
- Future element registry/global static registration을 추가하지 마라.
|
||
- Giant common result record with meaningless optional fields를 만들지 마라.
|
||
- 직접 commit하거나 hook script를 수동 실행하지 마라.
|