Files

Tarik Moussa 52604d8544 docs: Konzeptdokument Declarative YAML Pipeline (Phase 8e)

doc/concepts/declarative-pipeline.md — vollständige Design-Spezifikation:

  1. Kernidee: Processing Units mit expliziten require/provide-Contracts
  2. Token-Vokabular: 30 Tokens in 7 Kategorien
       input, setup, Gauss-Bonnet, solver, topology, layout, period/domain/output
  3. YAML-Schema: Vollständige Syntax inkl. Parameterdefaults aller Units
  4. Validierungsalgorithmus: monoton wachsendes provided-Set, Pre-Execution-Check
  5. 5 vollständige Beispiele:
       A — Euklidische Uniformisierung Torus (τ-Ausgabe)
       B — Sphärische Uniformisierung (cathead.obj)
       C — Hyperbolische Uniformisierung Torus (Poincaré-Disk)
       D — Volle Pipeline mit Periodenmatrix + 5×5-Kachelung
       E — Absichtlich fehlerhaftes Beispiel mit Validator-Fehlermeldungen
  6. C++-Mapping: alle YAML-Unit-Namen → C++-Funktionen + Header
  7. Implementierungsplan (Phase 8e): pipeline.hpp + CLI-App + YAML-Abhängigkeit
  8. Design-Entscheidungen: YAML vs. JSON/TOML, explizit vs. auto-inference,
     linear vs. DAG, eine Geometrie pro Datei

doc/api/cgal-package.md: Link zum Konzeptdokument ergänzt.
README.md: Link in Dokumentationstabelle ergänzt.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-18 01:39:14 +02:00

4.1 KiB

Raw Blame History

Phase 8 — CGAL Package Design

Status: planned. This document describes the target architecture for Phase 8. No code has been written yet. The design is informed by the CGAL package submission guidelines at https://www.cgal.org/developers.html

Goal

Integrate conformallab++ into the CGAL library as a proper CGAL package: Discrete_conformal_map. The package must satisfy all CGAL submission requirements: traits-class design, Doxygen documentation, CGAL-format test suite, and coverage of the CGAL coding conventions.

8a — Traits class & concepts

The current code is tightly coupled to CGAL::Surface_mesh<Point3>. Phase 8a introduces a traits class that separates the mesh type from the algorithm:

// TODO(Phase 8a): implement this header
// include/CGAL/Conformal_map_traits.h

template<
    typename MeshType,      // any CGAL halfedge mesh
    typename KernelType,    // CGAL kernel
    typename ScalarType = double
>
struct Conformal_map_traits {
    using Mesh   = MeshType;
    using Kernel = KernelType;
    using FT     = ScalarType;
    // ... vertex/edge/face descriptor types
    // ... property map access
};

Concept checks will ensure any user-provided mesh satisfies the halfedge mesh concept.

8b — Public header hierarchy

A clean public API separate from the internal implementation:

include/CGAL/
  Discrete_conformal_map.h        ← single user-facing include
  Conformal_map_traits.h
  Conformal_newton_solver.h
  Conformal_layout.h
  Conformal_cut_graph.h
  conformal_map_package.h         ← PackageDescription

All existing include/*.hpp headers remain as internal implementation details, not part of the public CGAL API.

8c — CGAL-style documentation

doc/Conformal_map/
  PackageDescription.txt
  User_manual.md
  Reference_manual.md
  fig/                            ← pipeline diagrams, mathematical figures

All public functions and concepts require Doxygen comments following the CGAL style.

8d — CGAL test format

test/Conformal_map/
  CMakeLists.txt                  ← CGAL-format, uses find_package(CGAL)
  test_euclidean_functional.cpp
  test_newton_solver.cpp
  ...

The existing GTest suite remains. CGAL-format tests are added alongside as a separate target, following the CGAL test infrastructure conventions.

8e — Declarative YAML pipeline

A lightweight YAML format for reproducible experiments. The CLI accepts --pipeline experiment.yml; the validator checks require/provide tokens before execution.

Full concept & design specification: doc/concepts/declarative-pipeline.md — token vocabulary, validation algorithm, 5 complete examples, implementation plan.

Abbreviated example:

pipeline:
  name: flat_torus_period
  geometry: euclidean

  input:
    source: data/torus.off

  steps:
    - id: setup
      unit: setup_euclidean_maps
      provide: [maps_initialised]

    - id: gauss_bonnet
      unit: enforce_gauss_bonnet
      require: [maps_initialised]
      provide: [gauss_bonnet_satisfied]

    - id: solve
      unit: newton_euclidean
      require: [gauss_bonnet_satisfied]
      params:
        tol: 1.0e-10
        max_iter: 200
      provide: [x_converged]

    - id: cut
      unit: compute_cut_graph
      require: [mesh_closed]
      provide: [cut_graph]

    - id: layout
      unit: euclidean_layout
      require: [x_converged, cut_graph]
      params:
        normalise: true
      provide: [layout_uv, holonomy]

    - id: period
      unit: compute_period_matrix
      require: [holonomy]
      provide: [tau]

  output:
    layout: out/torus_layout.off
    json:   out/torus_result.json
    tau:    out/torus_tau.txt

The contract table in contracts.md defines the valid require/provide token vocabulary.

TODO

Design Conformal_map_traits.h interface (8a)
Define concept requirements for MeshType (8a)
Create include/CGAL/ header skeleton (8b)
Write PackageDescription.txt (8c)
Port GTest tests to CGAL format (8d)
Implement YAML validator (8e)
CLI: --pipeline flag (8e)

4.1 KiB Raw Blame History