hullprod 1.0.0__tar.gz

hullprod-1.0.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to HullProd will be documented in this file.
+
+HullProd follows semantic versioning. Patch releases fix defects without
+breaking the public contract, minor releases add backward-compatible features,
+and major releases may change public schemas, formulas, CLI behavior, or field
+and output-layout contracts.
+
+## [1.0.0] - 2026-09-03
+
+### Added
+
+- A zero-configuration `hullprod INPUT` workflow for IGES, STEP, STL, OBJ, and
+  PLY, with automatic native-BRep or triangle-mesh backend selection.
+- The explicit recommended signature `I_D`, `I_D_plus`, `I_D_minus`, and the
+  four represented-valid-area curvature-class fractions.
+- Stable `signature.json`, one-row `signature.csv`, `validity.json`,
+  `provenance.json`, and concise text/HTML summaries.
+- ParaView-readable `surface_fields.vtp`, portable field CSV, and default
+  developability-density and curvature-class plots.
+- A shared `hullprod.assess(...)` Python API, deterministic automatic geometric
+  reference length, explicit `--lref`, and safe nonempty-output handling.
+- Small redistributable IGES and STL analytical examples for installed-wheel
+  smoke testing.
+- Clean-wheel validation on Linux with Python 3.10–3.12 and on macOS Apple
+  Silicon with Python 3.12, including native BRep and mesh inputs.
+
+### Changed
+
+- Standard installation now includes the `cadquery-ocp` dependency used for
+  native IGES/STEP evaluation; BRep global values do not come from display
+  tessellation.
+- Zero-configuration reference length now uses a rigid-motion-invariant
+  principal-axis projected span, with a centroid-radial fallback for isotropic
+  geometry; explicit user and configured benchmark reference lengths remain
+  authoritative.
+- Gaussian-curvature mesh results exclude invalid open-boundary vertices and
+  report represented-valid-area normalization and mesh-quality provenance.
+- The legacy `hullprod assess INPUT` command and raw metric keys remain
+  available for compatibility.
+- The default static HTML report is now a compact user view; full provenance,
+  validity, and numerical internals remain in linked machine-readable files.
+- Source/working units and the interpreted reference length are shown before
+  integration. Explicit reference lengths are compared with the automatic span
+  and receive a nonfatal warning below a 0.1 or above a 10 ratio.
+- Human-facing output distinguishes scientifically valid results from local
+  BRep quadrature cautions and mesh representation sensitivity.
+
+### Experimental and non-recommended quantities
+
+- Curvature energy, curvature fairness, section waviness, FFT section waviness,
+  and robust research variants are outside the recommended signature and
+  require explicit opt-in.
+- `developability_area_ratio` is auxiliary/redundant; local plate twist and
+  triangle/mesh-quality quantities are representation diagnostics.
+- HullProd does not provide a fabrication-cost, man-hour, forming-route, or
+  shipyard-calibrated composite score.

hullprod-1.0.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+type: software
+message: "If you use HullProd in scientific work, please cite the software and the related publication when available."
+title: "HullProd: Geometry-Based Producibility Metrics for Ship Hull Forms"
+version: "1.0.0"
+date-released: 2026-09-03
+authors:
+  - family-names: "Serani"
+    given-names: "Andrea"
+license: "BSD-3-Clause"
+repository-code: "https://github.com/cnr-inm-mao/hullprod"
+url: "https://github.com/cnr-inm-mao/hullprod"
+keywords:
+  - ship design
+  - hull forms
+  - producibility
+  - manufacturability
+  - geometry processing
+  - naval architecture

hullprod-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to HullProd
+
+HullProd is scientific software with a deliberately narrow scope: geometry-based
+producibility signatures from triangulated and native-BRep external hull
+surfaces. Contributions are welcome within that scope.
+
+## Scope of contributions
+
+Appropriate contributions include:
+
+- bug fixes;
+- improved mesh-quality diagnostics;
+- improved numerical robustness of existing metrics;
+- additional analytic tests;
+- benchmark workflows;
+- documentation improvements;
+- export utilities for visualization tools;
+- reproducible examples based on redistributable geometries.
+
+Contributions that require shipyard-specific production data, structural
+scantlings, cost models, man-hour models, or detailed fabrication planning
+should be discussed first because they lie outside the mesh/native-CAD
+geometry-assessment workflow.
+
+## Development setup
+
+A CPython 3.10, 3.11, or 3.12 environment is required.
+
+Create and activate a development environment with a supported interpreter:
+
+    python3.12 -m venv .venv
+    source .venv/bin/activate
+
+Install the package in editable mode with development dependencies:
+
+    python -m pip install -U pip
+    python -m pip install -e ".[dev]"
+
+## Checks before committing
+
+Before committing, please run:
+
+    ruff check .
+    pytest -q
+    python -m build
+    python -m twine check dist/*.whl dist/*.tar.gz
+    git diff --check
+
+## Coding style
+
+The project uses Ruff for linting. Code should favor clarity, explicit variable
+names, and reproducible numerical behavior over compactness. Pull requests
+should include focused tests and documentation for user-visible changes.
+
+## Scientific caution
+
+HullProd metrics are geometric descriptors. They should not be presented as direct predictors of fabrication cost, man-hours, shipyard productivity, or production schedule unless additional calibrated production data are introduced and validated.

hullprod-1.0.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andrea Serani
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

hullprod-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md LICENSE CITATION.cff CHANGELOG.md CONTRIBUTING.md
+recursive-include docs *.md

hullprod-1.0.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: hullprod
+Version: 1.0.0
+Summary: Geometry-based producibility assessment of ship hull forms from triangulated meshes and native IGES/STEP boundary representations.
+Author: Andrea Serani
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/cnr-inm-mao/hullprod
+Project-URL: Repository, https://github.com/cnr-inm-mao/hullprod
+Project-URL: Issues, https://github.com/cnr-inm-mao/hullprod/issues
+Keywords: ship design,hull forms,producibility,manufacturability,geometry processing,naval architecture
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Manufacturing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: trimesh>=4.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pandas>=1.5
+Requires-Dist: cadquery-ocp<7.10,>=7.9.3.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff==0.16.4; extra == "dev"
+Requires-Dist: vtk>=9.3; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: networkx>=3.0; extra == "benchmark"
+Requires-Dist: vtk>=9.3; extra == "benchmark"
+Dynamic: license-file
+
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/cnr-inm-mao/hullprod/main/assets/branding/hullprod-logo-horizontal.png"
+    alt="HullProd logo"
+    width="420"
+  >
+</p>
+
+# HullProd
+
+[![CI](https://github.com/cnr-inm-mao/hullprod/actions/workflows/ci.yml/badge.svg)](https://github.com/cnr-inm-mao/hullprod/actions/workflows/ci.yml)
+![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+**Geometry-based producibility screening for ship hull surfaces.**
+
+HullProd computes a compact signature of double-curvature intensity, sign, and
+areal composition directly from native IGES/STEP BRep geometry or triangulated
+STL/OBJ/PLY surfaces. It also exports distributed fields, plots, validity, and
+representation provenance.
+
+## Installation
+
+HullProd requires Python 3.10–3.12. The intended public installation command is:
+
+```bash
+pip install hullprod
+```
+
+One installation includes both the native OpenCascade and triangle-mesh
+backends; no separate CAD extra or system OpenCascade installation is required.
+
+## Quick start
+
+Assess native CAD directly:
+
+```bash
+hullprod myvessel.iges
+```
+
+The same command works for a triangulated surface:
+
+```bash
+hullprod myvessel.stl
+```
+
+HullProd selects the backend from the file extension and writes a predictable
+`myvessel_hullprod/` result directory.
+
+To supply the normalization length explicitly:
+
+```bash
+hullprod myvessel.iges --lref 200000
+```
+
+`--lref` uses the working length unit of the input geometry. For CAD imported
+in millimetres, `200000` means 200000 mm, or 200 m. HullProd prints the source
+unit, working unit, and interpreted value before integration and warns about a
+large discrepancy from the automatic geometric span without changing the
+supplied value.
+
+See [Getting started](docs/getting-started.md) for output-directory controls
+and other normal options.
+
+## Recommended signature
+
+HullProd 1.0 reports exactly:
+
+```text
+[I_D, I_D_plus, I_D_minus,
+ a_C_flat, a_C_single, a_C_elliptic, a_C_saddle]
+```
+
+- `I_D` measures total normalized double-curvature intensity.
+- `I_D_plus` and `I_D_minus` separate elliptic/synclastic and
+  saddle/reverse/anticlastic intensity.
+- The four `a_C` values are represented-valid-area fractions for flat, singly
+  curved, elliptic, and saddle/reverse regions.
+
+Together they describe **intensity**, **sign**, and **areal extent**. HullProd
+does not combine them into a universal scalar producibility score. The default
+quasi-zero factors are `h_f = k_f = 1e-4`; these are numerical classification
+thresholds, not manufacturing limits. See [Metrics](docs/metrics.md) for the
+equations and interpretation.
+
+## What HullProd produces
+
+A normal result directory contains:
+
+- `signature.json` and `signature.csv` for the recommended global signature;
+- `report.html` for a compact, static user report;
+- `validity.json` and `provenance.json` for scientific interpretation and audit;
+- `plots/` with developability-density and curvature-class maps; and
+- `fields/` with ParaView-readable VTP and portable CSV surface fields.
+
+The complete output contract and file roles are documented in
+[Outputs](docs/outputs.md).
+
+## Supported geometry
+
+| Representation | Formats | Backend |
+|---|---|---|
+| Native BRep | `.iges`, `.igs`, `.step`, `.stp` | Direct CAD derivatives and trimmed-domain quadrature |
+| Triangle mesh | `.stl`, `.obj`, `.ply` | Discrete curvature reconstruction on the supplied mesh |
+
+Unsupported formats fail with an actionable error; HullProd does not silently
+convert a BRep to a mesh for canonical global evaluation or fit CAD to a mesh.
+
+## BRep and mesh realizations
+
+Native BRep evaluation is the canonical realization when source CAD is
+available. Its global metrics come from direct surface derivatives and
+trimmed-domain integration, not from the display/export tessellation.
+
+Mesh evaluation is supported when triangulated geometry is the available
+representation. Its derivative-based values are explicitly
+representation-sensitive and should be interpreted with the recorded mesh
+quality and refinement provenance. This distinction does not make mesh results
+invalid; it makes their represented geometry part of the result.
+
+Without `--lref`, both backends use the same conceptual automatic convention: a
+rigid-motion-invariant principal-axis projected span, with a deterministic
+centroid-radial fallback for isotropic samples. It is recorded as
+`auto_principal_span` and is never described as `L_pp`.
+
+## Python API
+
+The Python API uses the same assessment pipeline as the CLI:
+
+```python
+from hullprod import assess
+
+result = assess("myvessel.iges")
+print(result.signature)
+```
+
+See the [Python API guide](docs/python-api.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Recommended metrics](docs/metrics.md)
+- [Result files and field exports](docs/outputs.md)
+- [Validity and provenance](docs/validity-and-provenance.md)
+- [Python API](docs/python-api.md)
+- [Experimental quantities](docs/experimental.md)
+- [Release history](CHANGELOG.md)
+
+README plus versioned Markdown under `docs/` are the complete v1 documentation
+system; no hosted documentation site is required.
+
+## Scientific scope and limitations
+
+HullProd is a geometry-based early-design screening tool, not a
+fabrication-cost predictor. It does not directly predict labor, forming route,
+production schedule, or shipyard-specific performance. It does not perform panelization, seam
+placement, forming simulation, optimization, or geometry repair.
+
+Auxiliary, mesh-diagnostic, and experimental quantities are kept separate from
+the recommended signature. Their status is explained in
+[Experimental quantities](docs/experimental.md).
+
+## Funding
+
+Development of HullProd was supported by the U.S. Office of Naval Research
+(ONR) through the Naval International Cooperative Opportunities in Science and
+Technology (NICOP) program, under Grant No. N00014-26-1-2164, as part of the
+BEAM project (*Bayesian Exploration and Optimization for Hull-form Architecture
+and Producibility Modeling*).
+
+The views and conclusions expressed in this software and its documentation are
+those of the authors and do not necessarily reflect the views of the Office of
+Naval Research.
+
+## Citation
+
+Please cite the software using [CITATION.cff](CITATION.cff). Cite the associated
+manuscript once final publication metadata are available; no DOI or journal
+record is claimed here before publication.
+
+## Contributing
+
+Bug reports, documentation corrections, reproducible analytical tests, and
+carefully scoped numerical improvements are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes to scientific
+definitions.
+
+## License
+
+HullProd is distributed under the [BSD-3-Clause license](LICENSE). The bundled
+analytical sphere fixtures are project-owned; restricted benchmark geometry is
+not redistributed.

hullprod-1.0.0/README.md

@@ -0,0 +1,192 @@
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/cnr-inm-mao/hullprod/main/assets/branding/hullprod-logo-horizontal.png"
+    alt="HullProd logo"
+    width="420"
+  >
+</p>
+
+# HullProd
+
+[![CI](https://github.com/cnr-inm-mao/hullprod/actions/workflows/ci.yml/badge.svg)](https://github.com/cnr-inm-mao/hullprod/actions/workflows/ci.yml)
+![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+**Geometry-based producibility screening for ship hull surfaces.**
+
+HullProd computes a compact signature of double-curvature intensity, sign, and
+areal composition directly from native IGES/STEP BRep geometry or triangulated
+STL/OBJ/PLY surfaces. It also exports distributed fields, plots, validity, and
+representation provenance.
+
+## Installation
+
+HullProd requires Python 3.10–3.12. The intended public installation command is:
+
+```bash
+pip install hullprod
+```
+
+One installation includes both the native OpenCascade and triangle-mesh
+backends; no separate CAD extra or system OpenCascade installation is required.
+
+## Quick start
+
+Assess native CAD directly:
+
+```bash
+hullprod myvessel.iges
+```
+
+The same command works for a triangulated surface:
+
+```bash
+hullprod myvessel.stl
+```
+
+HullProd selects the backend from the file extension and writes a predictable
+`myvessel_hullprod/` result directory.
+
+To supply the normalization length explicitly:
+
+```bash
+hullprod myvessel.iges --lref 200000
+```
+
+`--lref` uses the working length unit of the input geometry. For CAD imported
+in millimetres, `200000` means 200000 mm, or 200 m. HullProd prints the source
+unit, working unit, and interpreted value before integration and warns about a
+large discrepancy from the automatic geometric span without changing the
+supplied value.
+
+See [Getting started](docs/getting-started.md) for output-directory controls
+and other normal options.
+
+## Recommended signature
+
+HullProd 1.0 reports exactly:
+
+```text
+[I_D, I_D_plus, I_D_minus,
+ a_C_flat, a_C_single, a_C_elliptic, a_C_saddle]
+```
+
+- `I_D` measures total normalized double-curvature intensity.
+- `I_D_plus` and `I_D_minus` separate elliptic/synclastic and
+  saddle/reverse/anticlastic intensity.
+- The four `a_C` values are represented-valid-area fractions for flat, singly
+  curved, elliptic, and saddle/reverse regions.
+
+Together they describe **intensity**, **sign**, and **areal extent**. HullProd
+does not combine them into a universal scalar producibility score. The default
+quasi-zero factors are `h_f = k_f = 1e-4`; these are numerical classification
+thresholds, not manufacturing limits. See [Metrics](docs/metrics.md) for the
+equations and interpretation.
+
+## What HullProd produces
+
+A normal result directory contains:
+
+- `signature.json` and `signature.csv` for the recommended global signature;
+- `report.html` for a compact, static user report;
+- `validity.json` and `provenance.json` for scientific interpretation and audit;
+- `plots/` with developability-density and curvature-class maps; and
+- `fields/` with ParaView-readable VTP and portable CSV surface fields.
+
+The complete output contract and file roles are documented in
+[Outputs](docs/outputs.md).
+
+## Supported geometry
+
+| Representation | Formats | Backend |
+|---|---|---|
+| Native BRep | `.iges`, `.igs`, `.step`, `.stp` | Direct CAD derivatives and trimmed-domain quadrature |
+| Triangle mesh | `.stl`, `.obj`, `.ply` | Discrete curvature reconstruction on the supplied mesh |
+
+Unsupported formats fail with an actionable error; HullProd does not silently
+convert a BRep to a mesh for canonical global evaluation or fit CAD to a mesh.
+
+## BRep and mesh realizations
+
+Native BRep evaluation is the canonical realization when source CAD is
+available. Its global metrics come from direct surface derivatives and
+trimmed-domain integration, not from the display/export tessellation.
+
+Mesh evaluation is supported when triangulated geometry is the available
+representation. Its derivative-based values are explicitly
+representation-sensitive and should be interpreted with the recorded mesh
+quality and refinement provenance. This distinction does not make mesh results
+invalid; it makes their represented geometry part of the result.
+
+Without `--lref`, both backends use the same conceptual automatic convention: a
+rigid-motion-invariant principal-axis projected span, with a deterministic
+centroid-radial fallback for isotropic samples. It is recorded as
+`auto_principal_span` and is never described as `L_pp`.
+
+## Python API
+
+The Python API uses the same assessment pipeline as the CLI:
+
+```python
+from hullprod import assess
+
+result = assess("myvessel.iges")
+print(result.signature)
+```
+
+See the [Python API guide](docs/python-api.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Recommended metrics](docs/metrics.md)
+- [Result files and field exports](docs/outputs.md)
+- [Validity and provenance](docs/validity-and-provenance.md)
+- [Python API](docs/python-api.md)
+- [Experimental quantities](docs/experimental.md)
+- [Release history](CHANGELOG.md)
+
+README plus versioned Markdown under `docs/` are the complete v1 documentation
+system; no hosted documentation site is required.
+
+## Scientific scope and limitations
+
+HullProd is a geometry-based early-design screening tool, not a
+fabrication-cost predictor. It does not directly predict labor, forming route,
+production schedule, or shipyard-specific performance. It does not perform panelization, seam
+placement, forming simulation, optimization, or geometry repair.
+
+Auxiliary, mesh-diagnostic, and experimental quantities are kept separate from
+the recommended signature. Their status is explained in
+[Experimental quantities](docs/experimental.md).
+
+## Funding
+
+Development of HullProd was supported by the U.S. Office of Naval Research
+(ONR) through the Naval International Cooperative Opportunities in Science and
+Technology (NICOP) program, under Grant No. N00014-26-1-2164, as part of the
+BEAM project (*Bayesian Exploration and Optimization for Hull-form Architecture
+and Producibility Modeling*).
+
+The views and conclusions expressed in this software and its documentation are
+those of the authors and do not necessarily reflect the views of the Office of
+Naval Research.
+
+## Citation
+
+Please cite the software using [CITATION.cff](CITATION.cff). Cite the associated
+manuscript once final publication metadata are available; no DOI or journal
+record is claimed here before publication.
+
+## Contributing
+
+Bug reports, documentation corrections, reproducible analytical tests, and
+carefully scoped numerical improvements are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes to scientific
+definitions.
+
+## License
+
+HullProd is distributed under the [BSD-3-Clause license](LICENSE). The bundled
+analytical sphere fixtures are project-owned; restricted benchmark geometry is
+not redistributed.

hullprod-1.0.0/docs/experimental.md

@@ -0,0 +1,42 @@
+# Auxiliary, diagnostic, and experimental quantities
+
+The recommended HullProd 1.0 signature is limited to total and signed
+developability intensity plus the four curvature-class area fractions:
+
+```text
+I_D, I_D_plus, I_D_minus,
+a_C_flat, a_C_single, a_C_elliptic, a_C_saddle
+```
+
+Other quantities have deliberately different roles.
+
+## Auxiliary
+
+`developability_area_ratio` is the valid-area fraction above the shared
+Gaussian-curvature threshold. Under the common threshold it equals
+`a_C_elliptic + a_C_saddle`, so it is retained for compatibility but is not an
+independent signature component.
+
+## Mesh diagnostics
+
+Mesh-quality statistics, boundary information, triangle/edge statistics, and
+local plate twist describe the assessed representation. They help interpret
+mesh curvature reliability; they are not geometry-invariant signature
+components or manufacturing acceptance limits.
+
+## Screened experimental metrics
+
+`curvature_energy`, `curvature_fairness`, `section_waviness`,
+`section_waviness_fft`, and robust research variants were investigated but are
+not part of the recommended v1 signature. They are not computed or plotted by
+default.
+
+Request the screened set deliberately with:
+
+```bash
+hullprod myvessel.iges --experimental
+```
+
+Experimental values appear in a separately labelled JSON/report section and
+never enter `recommended_signature`. Their mathematical meanings and existing
+raw keys are preserved for research compatibility.