ConformalLabpp/doc/reviewer/cgal-submission-readiness-audit-2026-05-31.md

CGAL Submission-Readiness Audit — ConformalLabpp

Date: 2026-05-31 Auditor: External reviewer (Claude Opus 4.8) Scope: Readiness of the code/include/CGAL/ package for submission to the CGAL project (editorial-board review + integration into the CGAL release). Reference: CGAL Developer Manual — "Adding a new package", CGAL coding conventions, and the CGAL package directory structure.

This document is self-contained. A new session can pick up any finding below and act on it without prior context.

Status legend: ⛔ Blocker (submission rejected on sight) · 🔴 Critical · 🟡 Important · 🔵 Polish

Companion documents:

• external-audit-2026-05-30.md — port-faithfulness bugs
• test-coverage-error-handling-audit-2026-05-31.md — test gaps + error handling
• api-performance-audit-2026-05-31.md — API consistency + performance
• this file — CGAL submission readiness

Bottom line: the algorithmic maturity is strong, but the package is not submittable as-is. There are three hard blockers — provenance/porting rights (G0), licensing (G1), and directory layout (G2) — plus several CGAL-convention gaps. G0 is a legal precondition that gates everything else: until the right to port the original Varylab/TU-Berlin code is clarified with its authors, no license decision (G1) can be made and no public release or submission should happen. The remaining items are packaging and documentation-format work — substantial but mechanical, no research required.

---

Verdict at a glance

#	Sev	Title
G0	⛔	Porting rights unclear — the original Varylab/TU-Berlin project has no license (all rights reserved); the C++ code is a documented port (derivative work). Must clarify with the authors whether porting + (re)licensing is permitted before any license/release decision
G1	⛔	License is MIT — CGAL requires GPLv3+ (algorithmic) or LGPLv3+. Moot until G0 is resolved
G2	⛔	Directory layout is not CGAL package layout — no package_info/, no doc/<Pkg>/, tests/examples not in CGAL harness
G3	🔴	CGAL is vendored (code/deps/CGAL-6.1.1) — a CGAL package must not bundle CGAL
G4	🔴	Concept not in a Doxygen block — \cgalConcept is in // comments, won't render; no doc/<Pkg>/Concepts/ file
G5	🔴	No user manual — CGAL requires <Pkg>.txt (\mainpage) + PackageDescription.txt
G6	🔴	Test suite uses GoogleTest + FetchContent — CGAL uses its own test harness; external network deps are disallowed
G7	🟡	Primary template Default_conformal_map_traits is undefined — only Surface_mesh works; concept claims FaceGraph genericity
G8	🟡	.hpp extension for implementation headers — CGAL convention is .h
G9	🟡	Single-header monolith risk — heavy inline free functions in headers; CGAL prefers internal/ split + documented public surface
G10	🟡	No demo, no benchmark dir — recommended for a numeric package
G11	🔵	Naming inconsistencies carry into the public API (see api-performance-audit A1–A5)
G12	🔵	Copyright line — CGAL files carry an INRIA/GeometryFactory style header + the CGAL license boilerplate, not a bare MIT line

---

G0 — ⛔ Porting rights: the original is unlicensed and this is a derivative work

This is the precondition for everything else in this audit (and for the license finding G1). It must be resolved with the original authors before any public release, relicensing, or CGAL submission.

Disclaimer: the auditor is not a lawyer. This is a practical risk assessment, not legal advice. Confirm with the project owner / institutional legal counsel.

Evidence

The original project (gitlab.discretization.de:varylab/conformallab.git, mirrored to git.eulernest.eu) is the Varylab / TU-Berlin discrete-conformal codebase (DFG SFB/Transregio "Discretization in Geometry and Dynamics"; author circle around Stefan Sechelmann, Boris Springborn).

$ find /Users/tarikmoussa/Desktop/conformallab -maxdepth 2 \
       \( -iname 'license*' -o -iname 'copying*' \)
# → (nothing)
# Java sources carry NO license header; only build.xml + .project exist.

• The original has no LICENSE file and no per-file license headers → under default copyright law this means all rights reserved by the TU-Berlin/Varylab authors. "Publicly visible on an academic GitLab" is not a license grant.
• ConformalLabpp describes itself as a port: source comments say "Ported from de.varylab.discreteconformal.functional.EuclideanCyclicFunctional", and the test suite asserts "Java golden-oracle parity". That makes the C++ code a derivative work of the original source code, not merely an independent implementation of the published papers.

Why it blocks

A derivative work of all-rights-reserved code cannot be licensed by the porter alone — neither as MIT (the current state) nor as GPL (the CGAL requirement) — without permission from the original copyright holders. The existing MIT header on ConformalLabpp is therefore on shaky ground today, independent of CGAL.

Crucial distinction:

What was actually reproduced	Legal status
The published algorithms (Springborn 2020, Bobenko-Pinkall-Springborn 2010, Luo 2004)	Free to reimplement — mathematical methods are not copyrightable, only their concrete code expression
The source code of the Varylab Java project, line-by-line	Derivative work → requires the authors' permission to port and (re)license

The "Ported from …" comments currently document a code derivation in writing, which is the principal risk.

Action (owner-level, before any code/license change)

1. Determine provenance honestly: is ConformalLabpp a clean-room reimplementation from the papers, or a translation of the Varylab code? The current comments assert the latter.
2. Contact the original authors (Sechelmann / Springborn, TU Berlin / Varylab) to either (a) obtain written permission to port and relicense (ideally under GPLv3+ so CGAL submission stays open), or (b) confirm the original is intended to be freely reusable and get that in writing / as an added LICENSE upstream.
3. Pause public releases and CGAL submission until 1–2 are settled.
4. If permission cannot be obtained, the only clean path is a genuine clean-room reimplementation from the published papers, with the "Ported from …" provenance comments removed and replaced by paper citations.

Done when

• Written clarity exists on the right to port + (re)license the original code; the provenance comments in the source match that reality.

---

G1 — ⛔ License: MIT is incompatible with CGAL submission

Blocked by G0 — do not act on G1 until porting/relicensing rights are clear.

Evidence

All 41 headers carry:

// SPDX-License-Identifier: MIT

(grep -rh "SPDX-License-Identifier" code/include/ → 41× MIT, 0× anything else.)

Why it blocks

CGAL is dual-licensed: the algorithmic packages are GPLv3+, the foundational ones LGPLv3+, with a commercial license sold by GeometryFactory. A new package must be contributed under the same dual GPL/LGPL scheme, with copyright assigned or licensed appropriately. A package licensed MIT cannot be merged into the CGAL tree — the editorial board will reject it at intake.

Action

This is a licensing/legal decision for the project owner, not a code change:

1. Decide whether to relicense the contributed package as GPLv3+ (the normal choice for a new algorithmic CGAL package).
2. Replace every header's SPDX-License-Identifier: MIT with the CGAL license header boilerplate (see Installation/LICENSE* in the CGAL tree for the exact text and the $URL$ $Id$ SPDX-License-Identifier: GPL-3.0-or-later form).
3. Keep a separate MIT-licensed standalone build if a permissive standalone distribution is also desired (dual-distribution is possible but must be explicit).

⚠️ Do not auto-rewrite license headers without the owner's explicit decision — relicensing is irreversible for contributed copies and may involve other authors.

Done when

• Owner has chosen the license; headers carry the CGAL-conformant boilerplate.

---

G2 — ⛔ Directory layout is not a CGAL package

Evidence

Current layout:

code/include/CGAL/...        ← headers (good location)
code/examples/*.cpp          ← flat, not per-package
code/tests/cgal/*.cpp        ← GoogleTest, not CGAL harness
code/deps/CGAL-6.1.1         ← vendored CGAL (see G3)
(no package_info/ anywhere)
(no doc/<Pkg>/ with PackageDescription.txt)

CGAL expects a package rooted at a top-level package directory mirroring the CGAL source tree:

Discrete_conformal_map/
  include/CGAL/Discrete_conformal_map.h
  include/CGAL/Conformal_map/...
  doc/Discrete_conformal_map/
      Discrete_conformal_map.txt          (user manual, \mainpage)
      PackageDescription.txt              (\package_listing entries)
      Concepts/ConformalMapTraits.h       (the concept, doxygen-only)
      examples.txt, fig/
  examples/Discrete_conformal_map/*.cpp   (+ CMakeLists using CGAL macros)
  test/Discrete_conformal_map/*.cpp       (CGAL test harness)
  benchmark/Discrete_conformal_map/       (optional but recommended)
  package_info/Discrete_conformal_map/
      copyright  description.txt  dependencies  license.txt  maintainer

Action

Restructure into the CGAL package layout. This is mechanical but touches every file location and the build. Recommended approach:

1. Create the package_info/Discrete_conformal_map/ metadata files first (small).
2. Move headers under the package's include/CGAL/ (already close).
3. Re-home examples → examples/Discrete_conformal_map/, tests → test/Discrete_conformal_map/.
4. Build the doc/Discrete_conformal_map/ tree (G5).

Done when

• Layout matches an existing CGAL package (use e.g. Surface_mesh_parameterization or Heat_method_3 as a template — both are close in spirit).

---

G3 — 🔴 CGAL is vendored inside the repo

Evidence

code/deps/CGAL-6.1.1     ← full CGAL 6.1.1 source tree bundled

Why it matters

A package being submitted into CGAL must build against the surrounding CGAL tree, not bundle its own copy. The vendored CGAL-6.1.1 (and the standalone build wiring around it) is appropriate for the current standalone distribution, but must be removed from the submitted package — the package's dependencies file declares CGAL package dependencies instead.

Action

• For the CGAL-submission branch: drop code/deps/CGAL-*; rely on the host CGAL tree.
• Keep the vendored copy only on the standalone-distribution branch.
• List actual dependencies (Surface_mesh, BGL, Property_map, Solver_interface, Number_types, plus the external Eigen) in package_info/.../dependencies.

Done when

• The submission branch contains no bundled CGAL; it builds inside a CGAL checkout.

---

G4 — 🔴 The concept is not a documented CGAL concept

Evidence

code/include/CGAL/Conformal_map_traits.h:36-76 declares the concept with \cgalConcept, \concept ConformalMapTraits, \cgalHasModelsBegin/End — but the whole block uses plain // comments, not a Doxygen /*! ... */ block:

// ════════════════════════════════════════════════════════════════════════════
// \cgalConcept
//
// \concept ConformalMapTraits
...

Doxygen only parses /*! */ (or ///) blocks, so none of this renders. There is also no doc/<Pkg>/Concepts/ConformalMapTraits.h — in CGAL, concepts live as doxygen-only header files under the package doc/.../Concepts/ directory, separate from the model.

Action

1. Create doc/Discrete_conformal_map/Concepts/ConformalMapTraits.h containing the concept as a /*! \cgalConcept ... */-documented (empty) class, following the CGAL concept-file pattern.
2. Reference it via \cgalHasModels from Default_conformal_map_traits.
3. Convert the in-source // concept block to either a proper /*! */ block or remove it in favor of the doc/Concepts file.

Done when

• ConformalMapTraits appears in the generated reference manual under PkgConformalMapConcepts with its model linked.

---

G5 — 🔴 No CGAL user manual / PackageDescription

Evidence

find . -name PackageDescription.txt -o -path '*doc*' -name '*.txt' → none (outside deps/). The project has rich Markdown docs under doc/ (api/, math/, architecture/), but CGAL requires its own doxygen-driven manual files:

• doc/<Pkg>/<Pkg>.txt — the user manual with \mainpage-style narrative, \cgalExample references, figures.
• doc/<Pkg>/PackageDescription.txt — the \cgalPkgDescriptionBegin listing (authors, intro, license, dependencies, demo/example links) that populates the CGAL "Packages" overview.

Action

• Author Discrete_conformal_map.txt (user manual). Much of the content can be adapted from the existing doc/api/pipeline.md and doc/math/*.md.
• Author PackageDescription.txt with the standard CGAL macros.
• Wire both into a package doc/Doxyfile.in consistent with CGAL's doc build.

Done when

• cgal_create_package doc build produces a reference + user manual without warnings.

---

G6 — 🔴 Test suite is GoogleTest + FetchContent

Evidence

code/tests/cgal/CMakeLists.txt:

target_link_libraries(conformallab_cgal_tests PRIVATE GTest::gtest_main)
gtest_discover_tests(conformallab_cgal_tests ...)

(plus FetchContent for GoogleTest elsewhere in the build).

Why it matters

CGAL's test infrastructure uses its own harness (create_single_source_cgal_program, the test/ programs return 0/non-0, driven by the CGAL testsuite scripts). External network dependencies (FetchContent pulling GoogleTest) are not allowed in the CGAL tree, and the GoogleTest dependency would need vendoring or removal.

Action

This is the largest mechanical task. Options:

• (a) Port the assertions to CGAL's plain-assert + return EXIT_FAILURE test style, one program per test file under test/Discrete_conformal_map/. This is the canonical CGAL approach and removes the GoogleTest dependency entirely.
• (b) Keep GoogleTest for the standalone branch; maintain a parallel CGAL-style test/ tree for the submission branch.

The 272 existing tests are an asset — the assertions translate directly; only the framework scaffolding changes.

Done when

• test/Discrete_conformal_map/ runs under the CGAL testsuite with no GoogleTest.

---

G7 — 🟡 Genericity claimed but not delivered

Evidence

Conformal_map_traits.h:80-92: the primary template Default_conformal_map_traits<TriangleMesh, Kernel_> is declared but undefined; only the Surface_mesh partial specialization (:113) is implemented. The concept docstring (:13-21) advertises "can run on any CGAL halfedge mesh — Surface_mesh, Polyhedron_3, OpenMesh-adapter, pmp — without changes", and the API takes a TriangleMesh template parameter, implying BGL-generic support.

Why it matters

CGAL reviewers scrutinize generic-programming claims. Shipping a TriangleMesh template that compiles only for Surface_mesh is a documentation/implementation mismatch: a user passing a Polyhedron_3 gets a hard template error against an undefined primary template, not a clean diagnostic.

Action

Either:

• (a) Implement a generic FaceGraph/HalfedgeGraph path using boost::graph_traits
  • dynamic property maps (CGAL's dynamic_vertex_property_t), removing the Surface_mesh-only restriction — this is the "Phase 8a.2" already on the roadmap; or
• (b) Until then, narrow the documented contract: state explicitly that only Surface_mesh is supported, and static_assert a friendly message in the primary template instead of leaving it undefined.

Done when

• The advertised mesh-type support matches what compiles; unsupported types yield a static_assert message, not a raw template error.

---

G8 — 🟡 Header extension .hpp vs CGAL .h

Evidence

The implementation headers use .hpp (euclidean_functional.hpp, newton_solver.hpp, …), while the CGAL-facing headers correctly use .h (Discrete_conformal_map.h). CGAL's convention is .h for all headers.

Action

Rename the implementation headers to .h when they move under the package include/CGAL/Conformal_map/internal/ tree (G9), updating #include directives. Low-risk, mechanical; do it as part of the G2 restructure.

Done when

• All package headers use .h.

---

G9 — 🟡 Public/internal header surface is undivided

Evidence

The 26 code/include/*.hpp headers are all effectively public (flat in include/), mixing the user-facing CGAL entry points with low-level functional/geometry/solver internals (hyper_ideal_geometry.hpp, projective_math.hpp, clausen.hpp, …).

Why it matters

CGAL packages keep a small documented public API and move implementation into include/CGAL/<Pkg>/internal/. Exposing every helper as a top-level header makes the supported API surface ambiguous and the package harder to evolve without breaking users.

Action

• Designate the public surface (the CGAL/Discrete_* entry points, the traits, the layout/result types).
• Move everything else under include/CGAL/Conformal_map/internal/.
• Mark internal headers \internal for Doxygen (the parameters header already does this correctly — Conformal_map/internal/parameters.h is the right pattern).

Done when

• Only the intended public headers are documented; the rest are under internal/.

---

G10 — 🟡 No demo / benchmark directory

Evidence

No demo/ and no benchmark/ directory. For a numerical package, CGAL reviewers appreciate (and for some packages expect) a benchmark establishing performance characteristics, and a small demo is a strong plus.

Action

• Add benchmark/Discrete_conformal_map/ measuring solve time / iteration counts on the existing smoke meshes (cathead/brezel/brezel2) — this also dovetails with the performance findings in api-performance-audit-2026-05-31.md (B1/B4).
• A demo is optional; skip if time-constrained.

Done when

• A benchmark program exists and its numbers are referenced in the user manual.

---

G11 — 🔵 Public-API naming inconsistencies (cross-ref)

The naming inconsistencies documented in api-performance-audit-2026-05-31.md (findings A1–A5: assign_*, compute_*, gradient_check, the _map suffix, and the split result types) become public-API-stability concerns once the package is in CGAL, because CGAL APIs are expected to be stable across releases. Resolve A1–A5 before submission, not after — renaming a shipped CGAL API requires a deprecation cycle.

Done when

• A1–A5 resolved; the public names are the ones intended to be permanent.

---

G12 — 🔵 File header boilerplate

Evidence

Headers begin with // Copyright (c) 2024-2026 Tarik Moussa. + a bare SPDX line. CGAL files use a standardized header including the $URL$/$Id$ SVN/git keywords, the SPDX line in CGAL's form, and the copyright holder convention used in the tree.

Action

Adopt the CGAL file-header template (tied to the G1 license decision). Mechanical once G1 is settled.

Done when

• Headers match the CGAL file-header template.

---

What is already strong (genuine assets for submission)

• Named-parameter API is idiomatic: CGAL::parameters::gradient_tolerance(...) .max_iterations(...), with the tag machinery correctly placed in Conformal_map/internal/parameters.h and marked \internal. This is the hard part done right.
• Doxygen group hierarchy (PkgConformalMap / Ref / Concepts / NamedParameters) is set up correctly in doxygen_groups.h.
• The \internal discipline on the parameters header shows the author knows the public/internal distinction — it just needs to be applied to the other helpers (G9).
• Result types carry observability (sparse_qr_fallback_used, iteration counts).
• Algorithmic breadth + validation: five DCE models with Java golden-oracle parity and FD-gradient checks — a strong scientific basis, which is ultimately what the editorial board cares most about.
• Traits-based design intent is correct CGAL architecture; it only needs the genericity actually implemented (G7) and the concept properly documented (G4).

---

Suggested order of work (submission track)

0. G0 (porting rights) — owner-level legal precondition; contact the Varylab/TU-Berlin authors. Nothing below should ship publicly until this is resolved.
1. G1 (license decision) — follows directly from G0; pick GPLv3+ if submission stays the goal.
2. G2 + G3 + G8 (restructure) — do the layout move and header rename together; drop vendored CGAL on the submission branch.
3. G9 (public/internal split) — naturally part of the restructure.
4. G11 / A1–A5 (lock the public names) — before any docs are written against them. (A1–A3 are internal-API renames and are safe to do independently of G0; A4–A5 touch the public CGAL surface and should wait for the G0/G1 outcome.)
5. G4 + G5 (concept file + user manual + PackageDescription) — the doc deliverables.
6. G6 (CGAL test harness) — port the 272 tests off GoogleTest.
7. G7 (deliver or narrow genericity).
8. G10 (benchmark) + G12 (headers) — polish.

Realistic framing for the owner: the science is submission-grade; the gap is packaging + licensing + doc-format. None of items G2–G12 require new research, but collectively they are a significant, mostly-mechanical effort. G1 is a decision, not work.