Summary
Clarify the README-level scientific basis section and keep the detailed mathematical, numerical, and validation contract in focused docs. The goal is to make the crate easier for professors and outside reviewers to scan while preserving the full technical detail where it belongs.
Current State
The README already has a Scientific Basis section and links to references, invariants, numerical robustness, validation, and topology docs. The section can be sharpened into a compact reviewer-facing summary that points readers to the deeper documents.
Proposed Changes
README should keep:
- A short Scientific basis section near the introduction.
- The high-level model: finite point-set triangulations as oriented simplicial complexes with separate combinatorial and geometric checks.
- The robustness story: exact predicates, Simulation of Simplicity, deterministic construction, and validation hierarchy.
- A concise statement of what the crate guarantees and what it does not replace.
- Links to the detailed validation, invariant, topology, and numerical robustness docs.
Detailed docs should contain:
- The full validation hierarchy and failure modes.
- Predicate-kernel details, exact arithmetic, and degeneracy handling.
- Topology guarantees, PL-manifold versus pseudomanifold behavior, and repair semantics.
- Workflow-specific examples and edge cases.
Benefits
This keeps the README readable for scientific and AI-adjacent reviewers while preserving the crate's detailed correctness contract in maintainable topic docs.
Implementation Notes
Use the markov-chain-monte-carlo README/docs split as a model: compact summary in the README, canonical technical detail in docs. Keep the existing direct style and avoid marketing language.
Summary
Clarify the README-level scientific basis section and keep the detailed mathematical, numerical, and validation contract in focused docs. The goal is to make the crate easier for professors and outside reviewers to scan while preserving the full technical detail where it belongs.
Current State
The README already has a Scientific Basis section and links to references, invariants, numerical robustness, validation, and topology docs. The section can be sharpened into a compact reviewer-facing summary that points readers to the deeper documents.
Proposed Changes
README should keep:
Detailed docs should contain:
Benefits
This keeps the README readable for scientific and AI-adjacent reviewers while preserving the crate's detailed correctness contract in maintainable topic docs.
Implementation Notes
Use the markov-chain-monte-carlo README/docs split as a model: compact summary in the README, canonical technical detail in docs. Keep the existing direct style and avoid marketing language.