CDT++ 1.0.0
Causal Dynamical Triangulations in C++
Loading...
Searching...
No Matches
Utilities.hpp File Reference

Utility functions. More...

#include <CGAL/version.h>
#include <algorithm>
#include <array>
#include <charconv>
#include <cmath>
#include <concepts>
#include <cstdint>
#include <filesystem>
#include <fstream>
#include <gsl/gsl>
#include <iomanip>
#include <limits>
#include <locale>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <random>
#include <span>
#include <sstream>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
#include <version>
#include <date/date.h>
#include <fmt/ostream.h>
#include <spdlog/sinks/basic_file_sink.h>
#include <spdlog/sinks/stdout_color_sinks.h>
#include <spdlog/spdlog.h>
#include "Move_tracker.hpp"
#include "Random.hpp"
#include "Settings.hpp"
#include "Version.hpp"
Include dependency graph for Utilities.hpp:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  cdt::utilities::Generated_population_bounds
 Validated simplex-population bounds for generated triangulations. More...
struct  cdt::utilities::Move_statistics
 Cumulative counters needed to preserve observable run state. More...
 Provenance recorded next to every stochastic triangulation. More...
struct  cdt::utilities::Triangulation_artifact< TriangulationType >
 A validated triangulation artifact and its provenance. More...

Namespaces

namespace  cdt
 clang-15 does not support std::format

Typedefs

template<typename TriangulationType>
using cdt::utilities::Checkpoint_artifact = Triangulation_artifact<TriangulationType>
 A validated resumable checkpoint and its complete run state.
template<typename TriangulationType>
using cdt::utilities::Initial_triangulation_artifact
 A validated initial triangulation and its initialization provenance.

Enumerations

enum class  cdt::utilities::ArtifactKind { INITIAL_TRIANGULATION , CHECKPOINT , FINAL_TRIANGULATION }
 Persistence artifact represented by a triangulation payload. More...
enum class  cdt::Topology { cdt::TOROIDAL , cdt::SPHERICAL }
 Spatial-topology label stored by configuration and persistence APIs. More...

Functions

auto cdt::utilities::detail::artifact_name (ArtifactKind const artifact) -> std::string_view
auto cdt::utilities::detail::canonical_bipartite_incidence_records (std::vector< std::string > const &vertex_bases, std::vector< std::string > const &cell_bases, std::vector< std::vector< std::size_t > > const &cell_vertices) -> std::vector< std::string >
template<typename Signature>
auto cdt::utilities::detail::canonical_colors (std::vector< Signature > const &signatures) -> std::vector< std::size_t >
auto cdt::utilities::detail::canonical_incidence_search (std::vector< std::string > const &bases, std::vector< std::vector< std::size_t > > const &adjacency, std::vector< std::size_t > colors, std::size_t &budget) -> std::vector< std::string >
template<typename ManifoldType>
auto cdt::utilities::canonical_placement_fingerprint (ManifoldType const &manifold) -> std::uint64_t
 Fingerprint finite vertex coordinates and timeslice metadata.
template<typename TriangulationType>
auto cdt::utilities::detail::canonical_placement_fingerprint (TriangulationType const &triangulation) -> std::uint64_t
template<typename ManifoldType>
auto cdt::utilities::canonical_topology_fingerprint (ManifoldType const &manifold) -> std::uint64_t
 Fingerprint vertices, causal metadata, and abstract finite cells.
template<typename TriangulationType>
auto cdt::utilities::detail::canonical_topology_fingerprint (TriangulationType const &triangulation) -> std::uint64_t
void cdt::utilities::detail::consume_canonical_incidence_work (std::size_t &budget)
void cdt::utilities::create_logger ()
 Create console and file loggers.
auto cdt::utilities::current_date_time (std::chrono::system_clock::time_point const timestamp=std::chrono::system_clock::now())
 Return current date and time.
auto cdt::utilities::delaunay_tetrahedron_upper_bound (std::uint64_t const vertices) noexcept -> std::optional< std::uint64_t >
 Return the rigorous finite 3D Delaunay tetrahedron upper bound.
template<std::uniform_random_bit_generator Generator>
auto cdt::utilities::die_roll (Generator &generator)
 Roll a die using a caller-supplied std::uniform_random_bit_generator.
auto cdt::utilities::expected_points_per_timeslice (Int_precision const t_dimension, Int_precision t_number_of_simplices, Int_precision t_number_of_timeslices, double const initial_radius=1.0, double const foliation_spacing=1.0)
 Estimate the base population for the layered spherical generator.
auto cdt::utilities::detail::fingerprint_records (std::vector< std::string > const &records) -> std::uint64_t
template<std::uniform_random_bit_generator Generator>
auto cdt::utilities::generate_probability (Generator &generator)
 Generate a probability.
template<typename NumberType, class Distribution, std::uniform_random_bit_generator Generator>
auto cdt::utilities::generate_random (Generator &generator, NumberType t_min_value, NumberType t_max_value)
 Generate random numbers with a caller-supplied generator.
template<std::uniform_random_bit_generator Generator, std::integral IntegerType>
auto cdt::utilities::generate_random_int (Generator &generator, IntegerType t_min_value, IntegerType t_max_value)
 Generate random integers by calling generate_random, preserves template argument deduction.
template<std::uniform_random_bit_generator Generator, std::floating_point FloatingPointType>
auto cdt::utilities::generate_random_real (Generator &generator, FloatingPointType t_min_value, FloatingPointType t_max_value)
 Generate random real numbers by calling generate_random, preserves template argument deduction.
template<std::uniform_random_bit_generator Generator, std::integral IntegerType>
auto cdt::utilities::generate_random_timeslice (Generator &generator, IntegerType t_max_timeslice) -> decltype(auto)
 Generate a random timeslice.
auto cdt::utilities::generated_input_vertex_count (Int_precision const points_per_timeslice, Int_precision const timeslices, double const initial_radius, double const foliation_spacing) -> std::uint64_t
 Calculate the exact number of vertices generated on spherical layers.
auto cdt::utilities::generated_population_bounds (Int_precision const dimension, Int_precision const simplices, Int_precision const timeslices, double const initial_radius, double const foliation_spacing) -> Generated_population_bounds
 Calculate the generated point count and its upper bound.
auto cdt::utilities::gmpzf_to_double (Gmpzf const &t_value) -> double
 Convert Gmpzf into a double.
template<typename TriangulationType>
auto cdt::utilities::detail::has_coincident_vertices (TriangulationType const &triangulation) -> bool
auto cdt::utilities::detail::incidence_records_for_coloring (std::vector< std::string > const &bases, std::vector< std::vector< std::size_t > > const &adjacency, std::vector< std::size_t > const &colors) -> std::vector< std::string >
template<typename TriangulationType>
auto cdt::utilities::detail::incidence_topology_records (TriangulationType const &triangulation) -> std::vector< std::string >
template<typename ManifoldType>
auto cdt::utilities::make_filename (ManifoldType const &manifold)
 Generate the conventional state-derived OFF filename.
template<typename ManifoldType>
auto cdt::utilities::make_filename (ManifoldType const &manifold, cdt::RandomSeed const seed)
 Generate a filename that records the effective run seed.
template<typename ManifoldType>
auto cdt::utilities::make_filename (ManifoldType const &manifold, cdt::RandomSeed const seed, Int_precision const completed_passes)
 Generate a checkpoint filename that records seed and pass.
auto cdt::utilities::make_filename (Topology const &t_topology, Int_precision t_dimension, Int_precision t_number_of_simplices, Int_precision t_number_of_timeslices, double t_initial_radius, double t_foliation_spacing) -> std::filesystem::path
 Generate useful filenames.
template<typename ManifoldType>
auto cdt::utilities::make_reproducibility_metadata (ManifoldType const &manifold, cdt::RandomSeed const seed, ArtifactKind const artifact) -> Reproducibility_metadata
 Build provenance from a canonical manifold state.
auto cdt::utilities::metadata_filename (std::filesystem::path const &payload) -> std::filesystem::path
auto cdt::utilities::detail::metadata_text (Reproducibility_metadata const &metadata, Payload_integrity const payload) -> std::string
auto cdt::operator<< (std::ostream &t_os, Topology const &t_topology) -> std::ostream &
 Convert Topology to string output.
auto cdt::utilities::detail::parse_count_line (std::string const &line, std::string_view const prefix, std::filesystem::path const &path) -> std::uint64_t
auto cdt::utilities::detail::parse_info (std::string_view const text, std::filesystem::path const &path) -> Int_precision
template<std::floating_point Float>
auto cdt::utilities::detail::parse_metadata_floating (std::string_view const text, std::filesystem::path const &path) -> Float
auto cdt::utilities::detail::parse_metadata_integer (std::string_view const text, std::filesystem::path const &path) -> Int_precision
auto cdt::utilities::detail::parse_move_counts (std::string_view text, std::filesystem::path const &path) -> Move_statistics::Counts
template<typename TriangulationType>
auto cdt::utilities::detail::parse_payload (std::filesystem::path const &filename) -> TriangulationType
auto cdt::utilities::detail::parse_record (std::string const &line, std::string_view const prefix, std::filesystem::path const &path) -> std::pair< std::string, Int_precision >
auto cdt::utilities::detail::parse_unsigned (std::string_view const text, int const base, std::filesystem::path const &path) -> std::uint64_t
auto cdt::utilities::detail::payload_integrity (std::filesystem::path const &filename) -> Payload_integrity
auto cdt::utilities::detail::point_cell_key (auto const &cell) -> std::string
auto cdt::utilities::detail::point_key (auto const &point) -> std::string
template<typename Point>
auto cdt::utilities::point_to_str (Point const &t_point) -> std::string
 Covert a CGAL point to a string.
template<typename TriangulationType>
void cdt::utilities::print_delaunay (TriangulationType const &t_triangulation)
 Print triangulation statistics.
template<typename TriangulationType>
void cdt::utilities::detail::read_causal_info (std::istream &input, TriangulationType &triangulation, std::filesystem::path const &path)
template<typename TriangulationType>
auto cdt::utilities::read_checkpoint (std::filesystem::path const &filename) -> Triangulation_artifact< TriangulationType >
 Read a checkpoint that can continue the identical Markov chain.
template<typename TriangulationType>
auto cdt::utilities::read_file (std::filesystem::path const &filename) -> TriangulationType
 Read triangulation from file.
auto cdt::utilities::detail::read_indexed_info (std::istream &input, std::string_view const prefix, std::uint64_t const count, std::filesystem::path const &path) -> std::vector< Int_precision >
template<typename TriangulationType>
auto cdt::utilities::read_initial_triangulation (std::filesystem::path const &filename) -> Initial_triangulation_artifact< TriangulationType >
 Read a manifested initial triangulation for a new CDT run.
auto cdt::utilities::detail::read_persistence_metadata (std::filesystem::path const &path) -> Parsed_persistence_metadata
template<typename TriangulationType>
void cdt::utilities::detail::reconcile_payload_metadata (Reproducibility_metadata &metadata, TriangulationType const &triangulation)
auto cdt::utilities::detail::refine_incidence_colors (std::vector< std::vector< std::size_t > > const &adjacency, std::vector< std::size_t > colors, std::size_t &budget) -> std::vector< std::size_t >
void cdt::utilities::detail::replace_file (std::filesystem::path const &temporary, std::filesystem::path const &destination)
template<typename TriangulationType>
void cdt::utilities::detail::require_distinct_evolution_coordinates (TriangulationType const &triangulation, std::filesystem::path const &payload, std::filesystem::path const &sidecar, std::string_view const operation)
auto cdt::utilities::detail::standard_library_name () -> std::string
auto cdt::utilities::detail::to_reproducibility_metadata (Parsed_persistence_metadata const &source) -> Reproducibility_metadata
auto cdt::utilities::topology_to_str (Topology const &t_topology) -> std::string
 Convert a topology to a string using it's << operator.
template<typename ManifoldType>
void cdt::utilities::update_reproducibility_state (Reproducibility_metadata &metadata, ManifoldType const &manifold)
 Refresh state-dependent provenance after a transition sequence.
auto cdt::utilities::detail::validate_payload_integrity (std::filesystem::path const &payload) -> std::optional< Parsed_persistence_metadata >
template<typename TriangulationType>
void cdt::utilities::detail::validate_persistence_metadata (Parsed_persistence_metadata const &metadata, TriangulationType const &triangulation, std::filesystem::path const &payload_path, std::filesystem::path const &metadata_path)
template<typename TriangulationType>
void cdt::utilities::detail::validate_serialized_payload (std::filesystem::path const &filename, TriangulationType const &original)
template<typename TriangulationType>
auto cdt::utilities::detail::vertex_records (TriangulationType const &triangulation) -> std::vector< std::string >
template<typename TriangulationType>
void cdt::utilities::detail::write_causal_info (std::ostream &output, TriangulationType const &triangulation)
template<typename ManifoldType>
void cdt::utilities::write_file (ManifoldType const &t_universe)
 Write the runtime results to a file.
template<typename ManifoldType>
void cdt::utilities::write_file (ManifoldType const &t_universe, cdt::RandomSeed const seed)
 Write a triangulation with the effective seed in its filename.
template<typename ManifoldType>
void cdt::utilities::write_file (ManifoldType const &t_universe, cdt::RandomSeed const seed, Int_precision const completed_passes)
 Write a checkpoint with its effective seed and pass in its name.
template<typename ManifoldType>
void cdt::utilities::write_file (ManifoldType const &universe, Reproducibility_metadata const &metadata)
 Write a named stochastic artifact and its complete provenance.
template<typename TriangulationType>
void cdt::utilities::write_file (std::filesystem::path const &filename, TriangulationType const &triangulation)
 Write triangulation to file.
template<typename TriangulationType>
void cdt::utilities::write_file (std::filesystem::path const &filename, TriangulationType const &triangulation, Reproducibility_metadata const &metadata)
 Replace a triangulation and its verifiable provenance atomically per file.
auto cdt::utilities::detail::write_file_active () noexcept -> bool &
auto cdt::utilities::detail::write_file_mutex () -> std::mutex &
template<typename TriangulationType>
void cdt::utilities::detail::write_payload (std::filesystem::path const &filename, TriangulationType const &triangulation, std::optional< Reproducibility_metadata > const &metadata)
void cdt::utilities::detail::write_text (std::filesystem::path const &filename, std::string_view const contents)

Variables

constexpr std::size_t cdt::utilities::detail::CANONICAL_INCIDENCE_WORK_BUDGET {100'000}
constexpr std::string_view cdt::utilities::detail::CAUSAL_INFO_HEADER
template<typename TriangulationType>
constexpr bool cdt::utilities::detail::HAS_CAUSAL_INFO
constexpr bool cdt::utilities::detail::PARALLEL_TRIANGULATION_ENABLED {false}

Detailed Description

Utility functions.

Author
Adam Getchell

Definition in file Utilities.hpp.

Typedef Documentation

◆ Checkpoint_artifact

template<typename TriangulationType>
using cdt::utilities::Checkpoint_artifact = Triangulation_artifact<TriangulationType>

A validated resumable checkpoint and its complete run state.

Template Parameters
TriangulationTypePersisted triangulation representation.

Definition at line 2424 of file Utilities.hpp.

◆ Initial_triangulation_artifact

template<typename TriangulationType>
using cdt::utilities::Initial_triangulation_artifact
Initial value:
A validated triangulation artifact and its provenance.

A validated initial triangulation and its initialization provenance.

Template Parameters
TriangulationTypePersisted triangulation representation.

Definition at line 2370 of file Utilities.hpp.

Enumeration Type Documentation

◆ ArtifactKind

enum class cdt::utilities::ArtifactKind
strong

Persistence artifact represented by a triangulation payload.

Enumerator
INITIAL_TRIANGULATION 

Initial state before stochastic transitions.

CHECKPOINT 

Intermediate snapshot during a move run.

FINAL_TRIANGULATION 

Final state after the configured move run.

Definition at line 98 of file Utilities.hpp.

Function Documentation

◆ artifact_name()

auto cdt::utilities::detail::artifact_name ( ArtifactKind const artifact) -> std::string_view
inlinenodiscard

Definition at line 206 of file Utilities.hpp.

◆ canonical_bipartite_incidence_records()

auto cdt::utilities::detail::canonical_bipartite_incidence_records ( std::vector< std::string > const & vertex_bases,
std::vector< std::string > const & cell_bases,
std::vector< std::vector< std::size_t > > const & cell_vertices ) -> std::vector< std::string >
inlinenodiscard

Definition at line 422 of file Utilities.hpp.

◆ canonical_colors()

template<typename Signature>
auto cdt::utilities::detail::canonical_colors ( std::vector< Signature > const & signatures) -> std::vector< std::size_t >
nodiscard

Definition at line 286 of file Utilities.hpp.

◆ canonical_incidence_search()

auto cdt::utilities::detail::canonical_incidence_search ( std::vector< std::string > const & bases,
std::vector< std::vector< std::size_t > > const & adjacency,
std::vector< std::size_t > colors,
std::size_t & budget ) -> std::vector< std::string >
inlinenodiscard

Definition at line 388 of file Utilities.hpp.

◆ canonical_placement_fingerprint() [1/2]

template<typename ManifoldType>
auto cdt::utilities::canonical_placement_fingerprint ( ManifoldType const & manifold) -> std::uint64_t
nodiscard

Fingerprint finite vertex coordinates and timeslice metadata.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldManifold to fingerprint without mutation.
Returns
Stable placement fingerprint independent of handle identity.

Definition at line 2223 of file Utilities.hpp.

◆ canonical_placement_fingerprint() [2/2]

template<typename TriangulationType>
auto cdt::utilities::detail::canonical_placement_fingerprint ( TriangulationType const & triangulation) -> std::uint64_t
nodiscard

Definition at line 575 of file Utilities.hpp.

◆ canonical_topology_fingerprint() [1/2]

template<typename ManifoldType>
auto cdt::utilities::canonical_topology_fingerprint ( ManifoldType const & manifold) -> std::uint64_t
nodiscard

Fingerprint vertices, causal metadata, and abstract finite cells.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldManifold to fingerprint without mutation.
Returns
Stable topology fingerprint independent of handle identity.

Definition at line 2211 of file Utilities.hpp.

◆ canonical_topology_fingerprint() [2/2]

template<typename TriangulationType>
auto cdt::utilities::detail::canonical_topology_fingerprint ( TriangulationType const & triangulation) -> std::uint64_t
nodiscard

Definition at line 580 of file Utilities.hpp.

◆ consume_canonical_incidence_work()

void cdt::utilities::detail::consume_canonical_incidence_work ( std::size_t & budget)
inline

Definition at line 306 of file Utilities.hpp.

◆ create_logger()

void cdt::utilities::create_logger ( )
inline

Create console and file loggers.

Create a console and file loggers. There are six logging levels by default:

Logging level Description
Trace Used to trace the internals
Debug Diagnostic information
Info General information
Warn Errors that are handled
Err Errors which cause a function to fail
Critical Errors which cause the program to fail

A logging level covers all levels beneath it, e.g. trace covers everything, critical only shows up in spdlog::level::critical.

Logging levels and formatting are set by loggers. The sink is the object that writes the log to the target.

So, this function creates 3 sinks:

  1. Console, which logs Info and below to the terminal
  2. Debug, which logs Debug and below to logs/debug-log.txt
  3. Trace, which logs everything to logs/trace-log.txt

If an exception is thrown, then the default global console logger is used.

Definition at line 2871 of file Utilities.hpp.

◆ current_date_time()

auto cdt::utilities::current_date_time ( std::chrono::system_clock::time_point const timestamp = std::chrono::system_clock::now())
inlinenodiscard

Return current date and time.

Return current date and time in ISO 8601 format Use Howard Hinnant's date library to format UTC without requiring an external time zone database.

Parameters
timestampThe system time point to format
Returns
A formatted string with the system time in UTC
See also
https://github.com/HowardHinnant/date
https://en.cppreference.com/w/cpp/chrono/zoned_time

Definition at line 2044 of file Utilities.hpp.

◆ delaunay_tetrahedron_upper_bound()

auto cdt::utilities::delaunay_tetrahedron_upper_bound ( std::uint64_t const vertices) -> std::optional< std::uint64_t >
inlinenodiscardnoexcept

Return the rigorous finite 3D Delaunay tetrahedron upper bound.

Evaluates \((n^2-3n-2)/2=n(n-3)/2-1\) without overflowing. std::nullopt means that the exact bound exceeds uint64_t; it never means that the triangulation itself has that many tetrahedra.

Parameters
verticesNumber \(n\) of finite input vertices
Returns
The exact bound, or std::nullopt when it exceeds uint64_t
See also
Cheng, Dey, and Shewchuk, Chapter 4

Definition at line 2667 of file Utilities.hpp.

◆ die_roll()

template<std::uniform_random_bit_generator Generator>
auto cdt::utilities::die_roll ( Generator & generator)
inlinenodiscard

Roll a die using a caller-supplied std::uniform_random_bit_generator.

Template Parameters
GeneratorUniform random bit generator type.
Parameters
generatorGenerator whose state advances during sampling.
Returns
Uniform integer in the closed interval [1, 6].

Definition at line 2500 of file Utilities.hpp.

◆ expected_points_per_timeslice()

auto cdt::utilities::expected_points_per_timeslice ( Int_precision const t_dimension,
Int_precision t_number_of_simplices,
Int_precision t_number_of_timeslices,
double const initial_radius = 1.0,
double const foliation_spacing = 1.0 )
inlinenodiscard

Estimate the base population for the layered spherical generator.

The estimator is monotone in the requested simplex count. It takes the upper envelope of the historical piecewise schedules, thereby preserving their established scale without their downward jumps at 1,000, 10,000, and 100,000 requested simplices. This is a construction heuristic for CDT++'s nested cospherical inputs, with a 25% population margin to keep boundary layers populated. It is not Dwyer's distribution-specific expectation or an exact topology oracle.

See also
Dwyer's expected-complexity result
Parameters
t_dimensionNumber of dimensions
t_number_of_simplicesDesired post-repair tetrahedron count
t_number_of_timeslicesNumber of spherical layers
initial_radiusRadius of the first layer
foliation_spacingDistance between successive layers
Returns
Estimated base population parameter \(p\)
Exceptions
std::invalid_argumentif the dimension is not three or a count, radius, or spacing is not positive and finite
std::out_of_rangeif the requested estimate or generated vertex population is not representable

Definition at line 2707 of file Utilities.hpp.

◆ fingerprint_records()

auto cdt::utilities::detail::fingerprint_records ( std::vector< std::string > const & records) -> std::uint64_t
inlinenodiscard

Definition at line 557 of file Utilities.hpp.

◆ generate_probability()

template<std::uniform_random_bit_generator Generator>
auto cdt::utilities::generate_probability ( Generator & generator)
inlinenodiscard

Generate a probability.

Template Parameters
GeneratorUniform random bit generator type.
Parameters
generatorGenerator whose state advances during sampling.
Returns
Uniform long-double sample in [0, 1).

Definition at line 2593 of file Utilities.hpp.

◆ generate_random()

template<typename NumberType, class Distribution, std::uniform_random_bit_generator Generator>
auto cdt::utilities::generate_random ( Generator & generator,
NumberType t_min_value,
NumberType t_max_value )
nodiscard

Generate random numbers with a caller-supplied generator.

Accepts any uniform random bit generator. When callers provide cdt::Random, sampling uses its run-owned PCG engine.

See also
PCG random-number generators
Template Parameters
NumberTypeThe type of number in the RNG
DistributionThe distribution type, usually uniform
GeneratorA uniform random bit generator type
Parameters
generatorCaller-owned generator whose state advances during sampling
t_min_valueThe minimum value
t_max_valueThe maximum value
Returns
A random value in the distribution between min_value and max_value

Definition at line 2526 of file Utilities.hpp.

◆ generate_random_int()

template<std::uniform_random_bit_generator Generator, std::integral IntegerType>
auto cdt::utilities::generate_random_int ( Generator & generator,
IntegerType t_min_value,
IntegerType t_max_value )
nodiscard

Generate random integers by calling generate_random, preserves template argument deduction.

Template Parameters
GeneratorUniform random bit generator type.
IntegerTypeIntegral result type.
Parameters
generatorGenerator whose state advances during sampling.
t_min_valueInclusive lower bound.
t_max_valueInclusive upper bound.
Returns
Uniformly sampled integer in the requested closed interval.

Definition at line 2544 of file Utilities.hpp.

◆ generate_random_real()

template<std::uniform_random_bit_generator Generator, std::floating_point FloatingPointType>
auto cdt::utilities::generate_random_real ( Generator & generator,
FloatingPointType t_min_value,
FloatingPointType t_max_value )
nodiscard

Generate random real numbers by calling generate_random, preserves template argument deduction.

Template Parameters
GeneratorUniform random bit generator type.
FloatingPointTypeFloating-point result type.
Parameters
generatorGenerator whose state advances during sampling.
t_min_valueInclusive lower bound.
t_max_valueExclusive upper bound.
Returns
Uniformly sampled real value in the requested interval.

Definition at line 2579 of file Utilities.hpp.

◆ generate_random_timeslice()

template<std::uniform_random_bit_generator Generator, std::integral IntegerType>
auto cdt::utilities::generate_random_timeslice ( Generator & generator,
IntegerType t_max_timeslice ) -> decltype(auto)
nodiscard

Generate a random timeslice.

Template Parameters
GeneratorUniform random bit generator type.
IntegerTypeIntegral timeslice type.
Parameters
generatorGenerator whose state advances during sampling.
t_max_timesliceInclusive positive upper timeslice bound.
Returns
Uniformly sampled timeslice in [1, t_max_timeslice].

Definition at line 2561 of file Utilities.hpp.

◆ generated_input_vertex_count()

auto cdt::utilities::generated_input_vertex_count ( Int_precision const points_per_timeslice,
Int_precision const timeslices,
double const initial_radius,
double const foliation_spacing ) -> std::uint64_t
inlinenodiscard

Calculate the exact number of vertices generated on spherical layers.

For base population \(p\), initial radius \(r_0\), spacing \(\Delta r\), and \(T\) layers, this evaluates \(\sum_{i=0}^{T-1}\lfloor p(r_0+i\Delta r)\rfloor\) using the same long-double product and truncation boundary as make_foliated_ball(). Every per-layer conversion and the total are checked before narrowing.

Parameters
points_per_timesliceBase population \(p\) for the first layer
timeslicesNumber of spherical layers \(T\)
initial_radiusRadius \(r_0\) of the first layer
foliation_spacingRadius increment \(\Delta r\) per layer
Returns
Exact number of vertices supplied to CGAL
Exceptions
std::invalid_argumentif a count, radius, or spacing is not positive and finite
std::out_of_rangeif a layer or the accumulated vertex count cannot be represented by uint64_t

Definition at line 2616 of file Utilities.hpp.

◆ generated_population_bounds()

auto cdt::utilities::generated_population_bounds ( Int_precision const dimension,
Int_precision const simplices,
Int_precision const timeslices,
double const initial_radius,
double const foliation_spacing ) -> Generated_population_bounds
inlinenodiscard

Calculate the generated point count and its upper bound.

Parameters
dimensionNumber of dimensions
simplicesNumber of desired simplices
timeslicesNumber of desired timeslices
initial_radiusRadius of the first timeslice
foliation_spacingDistance between successive timeslices
Returns
Base population, last-layer point expression, exact input-vertex count, and representable finite 3D Delaunay tetrahedron bound
Exceptions
std::invalid_argumentif the dimension is not three or a count, radius, or spacing is not positive and finite
std::out_of_rangeif the requested estimate or generated vertex population is not representable

Definition at line 2813 of file Utilities.hpp.

◆ gmpzf_to_double()

auto cdt::utilities::gmpzf_to_double ( Gmpzf const & t_value) -> double
inlinenodiscard

Convert Gmpzf into a double.

This function is mainly for testing, since to_double() seems to work. However, if something more elaborate is required this function can be expanded.

Parameters
t_valueAn exact Gmpzf multiple-precision floating point number
Returns
The double conversion

Definition at line 2843 of file Utilities.hpp.

◆ has_coincident_vertices()

template<typename TriangulationType>
auto cdt::utilities::detail::has_coincident_vertices ( TriangulationType const & triangulation) -> bool
nodiscard

Definition at line 489 of file Utilities.hpp.

◆ incidence_records_for_coloring()

auto cdt::utilities::detail::incidence_records_for_coloring ( std::vector< std::string > const & bases,
std::vector< std::vector< std::size_t > > const & adjacency,
std::vector< std::size_t > const & colors ) -> std::vector< std::string >
inlinenodiscard
Precondition
colors is a permutation of [0, colors.size()), assigning every node a unique, valid color index.

Definition at line 353 of file Utilities.hpp.

◆ incidence_topology_records()

template<typename TriangulationType>
auto cdt::utilities::detail::incidence_topology_records ( TriangulationType const & triangulation) -> std::vector< std::string >
nodiscard

Definition at line 515 of file Utilities.hpp.

◆ make_filename() [1/4]

template<typename ManifoldType>
auto cdt::utilities::make_filename ( ManifoldType const & manifold)
nodiscard

Generate the conventional state-derived OFF filename.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldManifold whose geometry and foliation name the artifact.
Returns
Timestamped OFF path.

Definition at line 2110 of file Utilities.hpp.

◆ make_filename() [2/4]

template<typename ManifoldType>
auto cdt::utilities::make_filename ( ManifoldType const & manifold,
cdt::RandomSeed const seed )
nodiscard

Generate a filename that records the effective run seed.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldManifold whose state names the artifact.
seedEffective root seed.
Returns
OFF path containing the seed.

Definition at line 2124 of file Utilities.hpp.

References cdt::RandomSeed::value().

◆ make_filename() [3/4]

template<typename ManifoldType>
auto cdt::utilities::make_filename ( ManifoldType const & manifold,
cdt::RandomSeed const seed,
Int_precision const completed_passes )
nodiscard

Generate a checkpoint filename that records seed and pass.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldManifold whose state names the artifact.
seedEffective root seed.
completed_passesNumber of completed move passes.
Returns
OFF path containing seed and pass count.

Definition at line 2140 of file Utilities.hpp.

◆ make_filename() [4/4]

auto cdt::utilities::make_filename ( Topology const & t_topology,
Int_precision t_dimension,
Int_precision t_number_of_simplices,
Int_precision t_number_of_timeslices,
double t_initial_radius,
double t_foliation_spacing ) -> std::filesystem::path
inlinenodiscard

Generate useful filenames.

Parameters
t_topologyThe topology type from the scoped enum Topology
t_dimensionThe dimensionality of the triangulation
t_number_of_simplicesThe number of simplices in the triangulation
t_number_of_timeslicesThe number of time foliations
t_initial_radiusThe radius of the first foliation t=1
t_foliation_spacingThe spacing between foliations
Returns
A filename

Definition at line 2061 of file Utilities.hpp.

References cdt::SPHERICAL.

◆ make_reproducibility_metadata()

template<typename ManifoldType>
auto cdt::utilities::make_reproducibility_metadata ( ManifoldType const & manifold,
cdt::RandomSeed const seed,
ArtifactKind const artifact ) -> Reproducibility_metadata
nodiscard

Build provenance from a canonical manifold state.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
manifoldCanonical state summarized by the metadata.
seedEffective root seed.
artifactArtifact role to record.
Returns
Reconciled geometry, foliation, seed, and fingerprint metadata.

Definition at line 2237 of file Utilities.hpp.

◆ metadata_filename()

auto cdt::utilities::metadata_filename ( std::filesystem::path const & payload) -> std::filesystem::path
inlinenodiscard
Parameters
payloadTriangulation payload path.
Returns
Sidecar path formed by appending .meta.

Definition at line 181 of file Utilities.hpp.

◆ metadata_text()

auto cdt::utilities::detail::metadata_text ( Reproducibility_metadata const & metadata,
Payload_integrity const payload ) -> std::string
inlinenodiscard

Definition at line 645 of file Utilities.hpp.

◆ parse_count_line()

auto cdt::utilities::detail::parse_count_line ( std::string const & line,
std::string_view const prefix,
std::filesystem::path const & path ) -> std::uint64_t
inlinenodiscard

Definition at line 929 of file Utilities.hpp.

◆ parse_info()

auto cdt::utilities::detail::parse_info ( std::string_view const text,
std::filesystem::path const & path ) -> Int_precision
inlinenodiscard

Definition at line 816 of file Utilities.hpp.

◆ parse_metadata_floating()

template<std::floating_point Float>
auto cdt::utilities::detail::parse_metadata_floating ( std::string_view const text,
std::filesystem::path const & path ) -> Float
nodiscard

Definition at line 882 of file Utilities.hpp.

◆ parse_metadata_integer()

auto cdt::utilities::detail::parse_metadata_integer ( std::string_view const text,
std::filesystem::path const & path ) -> Int_precision
inlinenodiscard

Definition at line 832 of file Utilities.hpp.

◆ parse_move_counts()

auto cdt::utilities::detail::parse_move_counts ( std::string_view text,
std::filesystem::path const & path ) -> Move_statistics::Counts
inlinenodiscard

Definition at line 848 of file Utilities.hpp.

◆ parse_payload()

template<typename TriangulationType>
auto cdt::utilities::detail::parse_payload ( std::filesystem::path const & filename) -> TriangulationType
nodiscard

Definition at line 1704 of file Utilities.hpp.

◆ parse_record()

auto cdt::utilities::detail::parse_record ( std::string const & line,
std::string_view const prefix,
std::filesystem::path const & path ) -> std::pair< std::string, Int_precision >
inlinenodiscard

Definition at line 905 of file Utilities.hpp.

◆ parse_unsigned()

auto cdt::utilities::detail::parse_unsigned ( std::string_view const text,
int const base,
std::filesystem::path const & path ) -> std::uint64_t
inlinenodiscard

Definition at line 799 of file Utilities.hpp.

◆ payload_integrity()

auto cdt::utilities::detail::payload_integrity ( std::filesystem::path const & filename) -> Payload_integrity
inlinenodiscard

Definition at line 232 of file Utilities.hpp.

◆ point_cell_key()

auto cdt::utilities::detail::point_cell_key ( auto const & cell) -> std::string
inlinenodiscard

Definition at line 274 of file Utilities.hpp.

◆ point_key()

auto cdt::utilities::detail::point_key ( auto const & point) -> std::string
inlinenodiscard

Definition at line 267 of file Utilities.hpp.

◆ point_to_str()

template<typename Point>
auto cdt::utilities::point_to_str ( Point const & t_point) -> std::string
nodiscard

Covert a CGAL point to a string.

Template Parameters
PointThe type of point (e.g. 3D, 4D)
Parameters
t_pointThe point
Returns
A string representation of the point

Definition at line 2916 of file Utilities.hpp.

◆ print_delaunay()

template<typename TriangulationType>
void cdt::utilities::print_delaunay ( TriangulationType const & t_triangulation)

Print triangulation statistics.

Template Parameters
TriangulationTypeThe triangulation type
Parameters
t_triangulationA triangulation (typically a Delaunay_t<3> triangulation)

Definition at line 2155 of file Utilities.hpp.

◆ read_causal_info()

template<typename TriangulationType>
void cdt::utilities::detail::read_causal_info ( std::istream & input,
TriangulationType & triangulation,
std::filesystem::path const & path )

Definition at line 986 of file Utilities.hpp.

◆ read_checkpoint()

template<typename TriangulationType>
auto cdt::utilities::read_checkpoint ( std::filesystem::path const & filename) -> Triangulation_artifact< TriangulationType >
nodiscard

Read a checkpoint that can continue the identical Markov chain.

The complete manifested pair is validated before any state is returned. Snapshot-only legacy checkpoints, initial states, final states, malformed PCG state, and producer-toolchain mismatches are rejected. Distinct vertex coordinates are required for exact move-locator replay.

Template Parameters
TriangulationTypeThe type of triangulation.
Parameters
filenameCheckpoint payload path.
Returns
Validated triangulation plus exact stochastic continuation state.
Exceptions
std::filesystem::filesystem_errorfor an invalid or unsupported checkpoint contract.

Definition at line 2437 of file Utilities.hpp.

◆ read_file()

template<typename TriangulationType>
auto cdt::utilities::read_file ( std::filesystem::path const & filename) -> TriangulationType
nodiscard

Read triangulation from file.

Template Parameters
TriangulationTypeThe type of triangulation
Parameters
filenameThe file to read from
Returns
A Delaunay triangulation
Exceptions
std::filesystem::filesystem_errorif the payload is missing, unreadable, or malformed, or if a present sidecar is unreadable, malformed, or inconsistent with the payload.

Definition at line 2478 of file Utilities.hpp.

◆ read_indexed_info()

auto cdt::utilities::detail::read_indexed_info ( std::istream & input,
std::string_view const prefix,
std::uint64_t const count,
std::filesystem::path const & path ) -> std::vector< Int_precision >
inlinenodiscard

Definition at line 943 of file Utilities.hpp.

◆ read_initial_triangulation()

template<typename TriangulationType>
auto cdt::utilities::read_initial_triangulation ( std::filesystem::path const & filename) -> Initial_triangulation_artifact< TriangulationType >
nodiscard

Read a manifested initial triangulation for a new CDT run.

This boundary requires an initial-triangulation sidecar, verifies payload integrity and causal metadata, and returns the recorded foliation parameters needed to reconstruct the owning manifold. Checkpoints and final triangulations are rejected because this operation starts a new transition stream; it is not checkpoint resume. CDT evolution also requires distinct vertex coordinates because prepared move locators are coordinate-valued.

Template Parameters
TriangulationTypeThe type of triangulation.
Parameters
filenameInitial triangulation payload path.
Returns
Validated payload and initialization provenance.
Exceptions
std::filesystem::filesystem_errorif the payload or required sidecar is missing, malformed, inconsistent, or has another artifact role.

Definition at line 2387 of file Utilities.hpp.

◆ read_persistence_metadata()

auto cdt::utilities::detail::read_persistence_metadata ( std::filesystem::path const & path) -> Parsed_persistence_metadata
inlinenodiscard

Definition at line 1087 of file Utilities.hpp.

◆ reconcile_payload_metadata()

template<typename TriangulationType>
void cdt::utilities::detail::reconcile_payload_metadata ( Reproducibility_metadata & metadata,
TriangulationType const & triangulation )

Definition at line 1772 of file Utilities.hpp.

◆ refine_incidence_colors()

auto cdt::utilities::detail::refine_incidence_colors ( std::vector< std::vector< std::size_t > > const & adjacency,
std::vector< std::size_t > colors,
std::size_t & budget ) -> std::vector< std::size_t >
inlinenodiscard

Definition at line 316 of file Utilities.hpp.

◆ replace_file()

void cdt::utilities::detail::replace_file ( std::filesystem::path const & temporary,
std::filesystem::path const & destination )
inline

Definition at line 1680 of file Utilities.hpp.

◆ require_distinct_evolution_coordinates()

template<typename TriangulationType>
void cdt::utilities::detail::require_distinct_evolution_coordinates ( TriangulationType const & triangulation,
std::filesystem::path const & payload,
std::filesystem::path const & sidecar,
std::string_view const operation )

Definition at line 501 of file Utilities.hpp.

◆ standard_library_name()

auto cdt::utilities::detail::standard_library_name ( ) -> std::string
inlinenodiscard

Definition at line 219 of file Utilities.hpp.

◆ to_reproducibility_metadata()

auto cdt::utilities::detail::to_reproducibility_metadata ( Parsed_persistence_metadata const & source) -> Reproducibility_metadata
inlinenodiscard

Definition at line 1585 of file Utilities.hpp.

◆ topology_to_str()

auto cdt::utilities::topology_to_str ( Topology const & t_topology) -> std::string
inlinenodiscard

Convert a topology to a string using it's << operator.

Parameters
t_topologyThe Topology to convert
Returns
A string representation of the Topology

Definition at line 2926 of file Utilities.hpp.

◆ update_reproducibility_state()

◆ validate_payload_integrity()

auto cdt::utilities::detail::validate_payload_integrity ( std::filesystem::path const & payload) -> std::optional< Parsed_persistence_metadata >
inlinenodiscard

Definition at line 1629 of file Utilities.hpp.

◆ validate_persistence_metadata()

template<typename TriangulationType>
void cdt::utilities::detail::validate_persistence_metadata ( Parsed_persistence_metadata const & metadata,
TriangulationType const & triangulation,
std::filesystem::path const & payload_path,
std::filesystem::path const & metadata_path )

Definition at line 1824 of file Utilities.hpp.

◆ validate_serialized_payload()

template<typename TriangulationType>
void cdt::utilities::detail::validate_serialized_payload ( std::filesystem::path const & filename,
TriangulationType const & original )

Definition at line 1853 of file Utilities.hpp.

◆ vertex_records()

template<typename TriangulationType>
auto cdt::utilities::detail::vertex_records ( TriangulationType const & triangulation) -> std::vector< std::string >
nodiscard

Definition at line 473 of file Utilities.hpp.

◆ write_causal_info()

template<typename TriangulationType>
void cdt::utilities::detail::write_causal_info ( std::ostream & output,
TriangulationType const & triangulation )

Definition at line 604 of file Utilities.hpp.

◆ write_file() [1/6]

template<typename ManifoldType>
void cdt::utilities::write_file ( ManifoldType const & t_universe)

Write the runtime results to a file.

The filename is generated by the make_filename() and written using another write_file() function, which is currently implemented using the << operator for triangulations.

Template Parameters
ManifoldTypeThe manifold type
Parameters
t_universeThe simplicial manifold
Exceptions
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif persistence fails.

Definition at line 2291 of file Utilities.hpp.

◆ write_file() [2/6]

template<typename ManifoldType>
void cdt::utilities::write_file ( ManifoldType const & t_universe,
cdt::RandomSeed const seed )

Write a triangulation with the effective seed in its filename.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
t_universeManifold to serialize.
seedEffective root seed.
Exceptions
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif persistence fails.

Definition at line 2305 of file Utilities.hpp.

◆ write_file() [3/6]

template<typename ManifoldType>
void cdt::utilities::write_file ( ManifoldType const & t_universe,
cdt::RandomSeed const seed,
Int_precision const completed_passes )

Write a checkpoint with its effective seed and pass in its name.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
t_universeManifold to serialize.
seedEffective root seed.
completed_passesNumber of completed move passes.
Exceptions
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif persistence fails.

Definition at line 2321 of file Utilities.hpp.

◆ write_file() [4/6]

template<typename ManifoldType>
void cdt::utilities::write_file ( ManifoldType const & universe,
Reproducibility_metadata const & metadata )

Write a named stochastic artifact and its complete provenance.

Template Parameters
ManifoldTypeSupported manifold type.
Parameters
universeManifold to serialize.
metadataComplete artifact and stochastic provenance.
Exceptions
std::invalid_argumentif checkpoint metadata omits completed passes or input provenance is incomplete.
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif persistence fails.

Definition at line 2340 of file Utilities.hpp.

References cdt::utilities::Reproducibility_metadata::artifact, cdt::utilities::Reproducibility_metadata::completed_passes, and cdt::utilities::Reproducibility_metadata::seed.

◆ write_file() [5/6]

template<typename TriangulationType>
void cdt::utilities::write_file ( std::filesystem::path const & filename,
TriangulationType const & triangulation )

Write triangulation to file.

Writes CGAL's native triangulation stream using CDT++'s historical .off filename convention. This is not Geomview mesh OFF. Provides strong exception-safety for the destination file. Writes are serialized within the process and validated before an atomic replacement.

Template Parameters
TriangulationTypeThe type of triangulation
Parameters
filenameThe filename to write to
triangulationThe triangulation to write
Exceptions
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif serialization, validation, or replacement fails.

Definition at line 2178 of file Utilities.hpp.

◆ write_file() [6/6]

template<typename TriangulationType>
void cdt::utilities::write_file ( std::filesystem::path const & filename,
TriangulationType const & triangulation,
Reproducibility_metadata const & metadata )

Replace a triangulation and its verifiable provenance atomically per file.

Derives payload-dependent metadata from the triangulation and validates both temporary files before publishing the manifest and then the payload. The pair is not a filesystem transaction: interruption between replacements can leave a detectable checksum mismatch, which read_file() rejects.

Template Parameters
TriangulationTypeSupported Delaunay triangulation type.
Parameters
filenameDestination OFF path.
triangulationTriangulation payload to serialize.
metadataRun configuration and stochastic provenance.
Exceptions
std::invalid_argumentif input provenance is incomplete or does not identify an initial-triangulation artifact.
std::logic_errorfor a same-thread reentrant write.
std::filesystem::filesystem_errorif serialization, validation, or either replacement fails.

Definition at line 2201 of file Utilities.hpp.

◆ write_file_active()

auto cdt::utilities::detail::write_file_active ( ) -> bool &
inlinenodiscardnoexcept

Definition at line 1654 of file Utilities.hpp.

◆ write_file_mutex()

auto cdt::utilities::detail::write_file_mutex ( ) -> std::mutex &
inlinenodiscard

Definition at line 1648 of file Utilities.hpp.

◆ write_payload()

template<typename TriangulationType>
void cdt::utilities::detail::write_payload ( std::filesystem::path const & filename,
TriangulationType const & triangulation,
std::optional< Reproducibility_metadata > const & metadata )

Definition at line 1944 of file Utilities.hpp.

◆ write_text()

void cdt::utilities::detail::write_text ( std::filesystem::path const & filename,
std::string_view const contents )
inline

Definition at line 1910 of file Utilities.hpp.

Variable Documentation

◆ CANONICAL_INCIDENCE_WORK_BUDGET

std::size_t cdt::utilities::detail::CANONICAL_INCIDENCE_WORK_BUDGET {100'000}
inlineconstexpr

Definition at line 304 of file Utilities.hpp.

◆ CAUSAL_INFO_HEADER

std::string_view cdt::utilities::detail::CAUSAL_INFO_HEADER
inlineconstexpr
Initial value:
{
"cdt-plusplus-causal-info-v2"}

Definition at line 191 of file Utilities.hpp.

◆ HAS_CAUSAL_INFO

template<typename TriangulationType>
bool cdt::utilities::detail::HAS_CAUSAL_INFO
inlineconstexpr
Initial value:
=
requires(TriangulationType const& triangulation) {
triangulation.finite_vertex_handles();
triangulation.finite_cell_handles();
triangulation.number_of_vertices();
triangulation.number_of_finite_cells();
}

Definition at line 464 of file Utilities.hpp.

◆ PARALLEL_TRIANGULATION_ENABLED

bool cdt::utilities::detail::PARALLEL_TRIANGULATION_ENABLED {false}
inlineconstexpr

Definition at line 197 of file Utilities.hpp.