Unit-safe, strongly typed, validated input parameters for scientific and engineering software.
Focus on your science. Leave the parameter plumbing to SciNumTools.
SciNumTools provides a common representation for physical quantities and validated scientific input parameters. Its C++17 libraries can be used from C/C++, Python, the command line, and CMake.
The project is built around two languages:
- PUEL describes values, units, uncertainties, arrays, and unit systems. See the PUEL language specification.
- DIPL describes typed input parameters, constraints, and relationships. See the DIPL language specification.
DIPL can serve as the single source of validated truth for a scientific model: values, units, constraints, derived relationships, and provenance stay together in one portable definition rather than being distributed across configuration files and application code.
The online documentation contains the concepts, language specifications, tutorials, examples, and API reference. The official SNT3 benchmarking project is scinumtools/snt-bench.
Scientific software often begins with a small configuration file, then grows into values spread across input files, unit conversions, validation code, derived constants, and undocumented assumptions. That makes a model harder to review, reproduce, and safely reuse in another tool or language.
DIPL was created to make the parameter definition itself the authoritative model interface. It keeps physical units, types, constraints, hierarchical structure, references, expressions, metadata, and provenance together, then exposes one evaluated and validated environment to every part of an application. The result is less duplicated glue code and a clearer boundary between a scientific model's assumptions and its implementation.
- Unit-aware quantities: Calculate and convert values with units, uncertainties, arrays, prefixes, and unit systems.
- Validated parameter models: Define typed DIPL hierarchies with constraints, expressions, dependencies, and metadata.
- Reviewable changes: Inspect provenance, preview overrides, and compare evaluated environments before accepting new settings.
- Portable results: Save DIPH5 snapshots with source-content hashes, or generate files for C++, C, Fortran, Rust, Julia, JSON, and YAML.
- Readable reports: Generate reports with effective values, units, overrides, provenance, schemas, and references in TeX, PDF, Markdown, HTML, and other formats.
- C++ API: C++17 reference for quantities, DIPL, and application commands.
- Python: Bindings for PUQ, DIP, and API, including NumPy arrays.
- C binding: Experimental PUQ and DIPL interfaces using opaque handles.
- WebAssembly and JavaScript: Browser-side tools for DIPL inspection and PUQ conversion.
- Command line: PUQ, DIPL, export, and report commands, plus formatting, validation, and linting.
- Parameter Viewer: Graphical browser for DIPL projects, DIPH5 snapshots, dependencies, and provenance.
- CMake: Package integration and DIPL evaluation during configuration.
- REST API server: Local HTTP service for the command-oriented PUQ and DIP API.
- MCP for AI agents: Native
snt mcpserver with DIPL and PUQ tools over stdio or Streamable HTTP. - Docker: Images for Python, development, REST, and MCP.
See the documentation index for the complete usage guides.
Define parameters in a parameters.dip file:
simulation
title str = "Cylinder flow"
fluid
density float = 998.2 kg/m3
!condition ({.} > 0 kg/m3)
viscosity float = 1.003e-3 Pa*s
time
timestep float = 1e-3 s
end float = 10 s
steps int = ({?simulation.time.end} / {?simulation.time.timestep})
boundary[inlet]
velocity float[3] = [1.0, 0.0, 0.0] m/s
solver
type str = "steady"
!options ["steady", "transient"]
The same definition can be read from C++, Python, and the command line. For persistence, exports, and reports, see the CLI guide.
Use the PUQ and DIP APIs from C++:
#include <snt/puq/quantity.h>
#include <snt/dip/dip.h>
#include <cstdint>
#include <iostream>
int main() {
snt::puq::Quantity length("3.048*m");
std::cout << length.convert("US_ft").to_string() << "\n";
snt::dip::DIP dip;
dip.add_file("parameters.dip");
auto env = dip.parse();
std::cout << env["simulation.fluid.density"].as<double>() << "\n";
std::cout << env["simulation.time.steps"].as<int64_t>() << "\n";
}Use the same functionality from Python:
from scinumtools3.puq import Quantity
from scinumtools3.dip import DIP
length = Quantity(3.048, "m").convert("US_ft")
print(length.to_string())
dip = DIP()
dip.add_file("parameters.dip")
env = dip.parse()
print(env["simulation.fluid.density"].value)
print(env["simulation.time.steps"].value)The command-line interface can consume the same definitions:
$ snt puq convert "3.048*m" ft -s SI -S US
10*ft
$ snt dip parse -i file parameters.dip -r simulation.fluid.density --print
density = 998.2 kg*m-3See the quickstart and examples for complete examples.
For Python, install from PyPI with pip install scinumtools3 or from
conda-forge with conda install conda-forge::scinumtools3.
For C++, use vcpkg install scinumtools3. On macOS, use
brew tap scinumtools/tap followed by brew install scinumtools3.
To install the precompiled snt command without administrator rights on
Linux x86-64 or macOS ARM64, run:
curl -fsSLO https://raw.githubusercontent.com/scinumtools/snt3/main/packaging/installers/install-cli.sh
sh install-cli.shOn Windows x86-64, use the PowerShell installer. See the installation guide for Windows commands, offline installation, Conan, and source builds.
After installation, find the package and link the modules required by an application:
find_package(snt REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE snt-api snt-dip)The CMake integration can also parse a DIP file while configuring a project. The resulting values are available as CMake variables for the rest of the configuration process:
find_package(snt REQUIRED)
snt_dip_get(
FILE parameters.dip
PATH simulation.time.steps
OUT SIMULATION_STEPS
REQUIRED
)
We are inviting maintainers of established, open-source scientific codes to try a shared, optional parameter layer. A project-specific adapter can turn a DIPL definition into its existing native input file, while SciNumTools handles units, constraints, dependencies, and parameter documentation. The first step keeps the solver and its native parser in place. Read about the initiative and see the full flyer. The long-term aim is direct integration where a project judges the model and tooling stable and trustworthy. Explore related projects and integrations in the SNT Hub registry.
With SNT installed, create a workspace and choose a Hub project:
mkdir study && cd study
snt hub list
snt hub fetch PROJECT
snt hub examples
snt hub setup EXAMPLEReplace PROJECT and EXAMPLE with names listed by list and examples.
Generated files are placed in runs/EXAMPLE;
see the SNT Hub CLI guide for prerequisites and overrides.
AI assistants, including large language models (LLMs), can draft scientific setups, but those drafts need explicit checks. DIPL gives them a readable, structured description of run settings and references to initial-condition files. SciNumTools checks declared types, units, constraints, and dependencies; a code-specific adapter can check further requirements and write the code's native input files. This makes an AI-assisted setup easier to inspect and test before a run. Scientific review is still needed to judge whether the choices are physically appropriate.
The current tools let an assistant or script list and describe evaluated parameters, then preview proposed overrides as JSON. The same operations are available through the C++ inspection API and Python bindings.
The native snt mcp interface
lets AI agents validate, compare, and export DIPL candidates.
Try the runnable UsingMCP example.
Nuclide Atlas is a unit-aware nuclear-isotope database and decay-chain calculator built with SciNumTools3. It uses DIPL for validated nuclide data, scenarios, provenance, and CMake build configuration.
See more applications and examples.
The repository contains the C++ sources, Python bindings, command-line applications, tests, examples, packaging tools, and documentation.
SciNumTools v3 is the compiled successor to the original SciNumTools v2, with the same focus on units and validated scientific parameters.
Contributions and issue reports are welcome through GitHub. See CONTRIBUTING.md for the development workflow.
SciNumTools is released under the MIT License.