CoreToolkit
Core C++ library powering VOLT's atomistic simulation analysis. Provides math primitives, spatial data structures, neighbor search, simulation cell handling, and the plugin build system.
TL;DR — CoreToolkit is the C++23 static library every VOLT plugin links against. Build with CMake + Conan 2.
Overview
The Foundational Algorithms rely on CoreToolkit.
| Language | C++23 |
| Build system | CMake ≥ 3.20 + Conan 2 |
| Package type | Static library (libcoretoolkit.a) |
| License | MIT |
| Links | GitHub |
Modules
Seven modules under the include/volt/ namespace:
volt/math
Linear algebra and geometry primitives.
| Header | Description |
|---|---|
vector2.h / vector3.h / vector4.h | 2D, 3D, and 4D vector types |
point2.h / point3.h | 2D and 3D point types |
matrix3.h / matrix4.h | 3×3 and 4×4 matrix types |
quaternion.h | Quaternion for rotation representation |
rotation.h / scaling.h | Rotation and scaling transformations |
affine_transformation.h | General affine transformation |
affine_decomposition.h | Decomposition of affine transforms |
symmetric_tensor.h | Symmetric tensor (e.g. strain tensors) |
box3.h | 3D axis-aligned bounding box |
plane.h | Plane representation |
ray.h | Ray for geometric queries |
lin_alg.h | Linear algebra utilities |
volt/core
Data model for atomistic simulations.
| Header | Description |
|---|---|
simulation_cell.h | Simulation cell (box vectors, periodicity) |
frame_adapter.h | Adapter for reading simulation frames |
lammps_parser.h | High-performance LAMMPS dump parser |
particle_property.h | Per-particle property storage |
property_base.h | Type-erased property base class |
analysis_result.h | Standard result type for analysis plugins |
volt.h | Precompiled header (std lib + spdlog + boost::dynamic_bitset + math/lin_alg.h + common constants and forward declarations) for the library and all plugins |
volt/analysis
Spatial query algorithms used by analysis plugins.
| Header | Description |
|---|---|
cutoff_neighbor_finder.h | Distance-cutoff neighbor search (cell-list based) |
nearest_neighbor_finder.h | k-nearest neighbor search (KD-tree based) |
volt/structures
Higher-level crystallographic data structures.
| Header | Description |
|---|---|
cluster.h | Cluster representation for defect analysis |
crystal_structure_types.h | Crystal structure type enumerations (FCC, HCP, BCC, diamond, etc.) consumed by volt/plugin/option_binding.h |
volt/utilities
General-purpose infrastructure.
| Header | Description |
|---|---|
memory_pool.h | Thread-safe arena-style memory pool |
bounded_priority_queue.h | Fixed-capacity priority queue for k-NN search |
json_utils.h | JSON serialization helpers (nlohmann/json), including parquet output |
parquet_atom_writer.h | Streams per-atom output to a _atoms.parquet file in the canonical AtomisticExporter format (used by volt/plugin/output_serializer.h) |
volt/cli
CLI scaffolding for plugin executables.
| Header | Description |
|---|---|
common.h | Argument parsing, I/O paths, and JSON output helpers shared by all plugin binaries |
volt/plugin
The plugin-authoring API. These headers wrap plugin-executable boilerplate so an algorithm only implements its compute() step.
| Header | Description |
|---|---|
plugin_main.h | pluginMain() driver and the VOLT_PLUGIN_MAIN macro: parses CLI args, loads the LAMMPS frame (and optional --reference frame), sets OneTBB thread limits via --threads, then invokes the plugin's run function |
plugin_entry.h | VOLT_SERVICE_PLUGIN macro that wires a service type's compute() method to pluginMain, binding UI arguments and selecting the 2- or 3-argument compute() overload |
option_binding.h | Binds plugin.json UI arguments to service setters (opt(...), applyAll, optionsMeta), including lattice-type options resolved against crystal_structure_types.h |
output_serializer.h | serializePluginOutput() writes the summary {outputBase}{suffix}.parquet and, when a bucket resolver is supplied, a separate {outputBase}_atoms.parquet |
particle_id_mapper.h | Builds current↔reference particle index mappings from atom IDs (for reference-frame analyses such as displacement) |
Dependencies
Managed via Conan 2:
| Dependency | Version | Purpose |
|---|---|---|
| Boost | 1.88.0 | Header-only utilities |
| oneTBB | 2021.12.0 | Parallel algorithms & concurrency |
| spdlog | 1.14.1 | Structured logging |
| nlohmann_json | 3.11.3 | JSON I/O |
Three more libraries are vendored under dependencies/: MWM_CSP and Geogram are compiled as static libraries, fast_float is header-only (installed as headers):
| Library | Purpose |
|---|---|
| MWM_CSP | Minimum-weight matching for centrosymmetry parameter calculation |
| Geogram | Delaunay tessellation (PSM subset) |
| fast_float | Header-only fast string-to-float parser |
Build Flags
GCC/Clang Release builds apply these flags, propagated to all consumers via PUBLIC:
-O3 -mtune=generic -fno-math-errno -fno-trapping-math -ffp-contract=fastCPU-specific tuning is opt-in: -DVOLT_ENABLE_NATIVE_OPTIMIZATIONS=ON (default OFF) swaps -mtune=generic for -march=native.
Avoids -ffast-math globally to preserve strict IEEE compliance on geometry-critical code paths.
CI / GitHub Actions
CoreToolkit exposes a reusable workflow at .github/workflows/build-plugin-binary.yml that any plugin repository can call to:
- Build the plugin against a fresh CoreToolkit checkout across a matrix of
ubuntu-latest(linux/x86_64),macos-latest(darwin/arm64), andwindows-latest(windows/x86_64). CoreToolkit and anydependency_reposare exported to Conan first. - Bundle the install tree (
bin/,lib/,scripts/,share/) together withplugin.jsoninto a Zstandard-compressed.tar.zstarchive plus a.sha256checksum (via.github/scripts/build_plugin_bundle.py). Library-only plugins with no executable entrypoint are skipped. - Publish a GitHub Release tagged
v<version>with the bundles attached (softprops/action-gh-release). On tag pushes, a separate job also publishes the bundles to the Registry viavpm publish.
Bundle file naming follows:
<key>-<version>-<os>-<arch>.tar.zst
<key>-<version>-<os>-<arch>.tar.zst.sha256where <key> and <version> come from the plugin's plugin.json modifier node, and <os>-<arch> is one of linux-x86_64, darwin-arm64, or windows-x86_64.