scinumtools3 0.5.0

Python bindings for the scinumtools3 C++ core

SciNumTools3 for Python

Unit-safe quantities, runtime expressions, and validated scientific parameters for Python.

SciNumTools3 helps eliminate hidden assumptions in scientific software by providing:

• ✅ Physical quantities with units
• ✅ Automatic unit conversion
• ✅ Runtime expression evaluation
• ✅ Validated input parameters
• ✅ Structured scientific configuration files
• ✅ Consistent parameter handling across simulation and analysis workflows

Relationship to the C++ Core

scinumtools3 is the official Python binding for the SciNumTools3 C++ project.

The Python package exposes the same core concepts used by the C++ implementation, including:

• Physical Units & Quantities (PUQ)
• Dimensional Input Parameters (DIP)
• Runtime expression evaluation
• Unit-aware validation and conversion

This enables consistent parameter definitions and unit handling across Python analysis workflows and C++ simulation codebases.

C++ Project

The underlying C++ implementation is available on GitHub:

https://github.com/vrtulka23/scinumtools3

The C++ project serves as the reference implementation and provides high-performance support for scientific computing, numerical simulations, and HPC workflows.

---

Installation

Install directly from PyPI:

pip install scinumtools3

PyPI package:

https://pypi.org/project/scinumtools3/

---

Why SciNumTools3?

Scientific workflows frequently suffer from:

• inconsistent unit handling
• manual conversion mistakes
• duplicated parameter definitions
• missing validation
• configuration drift between simulation and analysis code

SciNumTools3 provides a unified framework for defining, validating, and evaluating scientific parameters while preserving physical units throughout calculations.

---

Core Features

Physical Quantities

Create quantities with physical units and perform automatic conversions:

from scinumtools3.puq import Quantity

length = Quantity("1*m")
length = length.convert("km")

print(length)
# 1e-3*km

---

Unit-Aware Arithmetic

from scinumtools3.puq import Quantity

distance = Quantity("1000*m")
time = Quantity("100*s")

velocity = distance / time

print(velocity)
# 10*m*s-1

---

Validated Parameters (DIP)

Define scientific parameters with units, constraints, and dependencies.

from scinumtools3.dip import DIP

dip = DIP()

dip.add_string("temperature float = 300 K")
dip.add_string("pressure float = 1 atm")

env = dip.parse()

Example parameter specification:

simulation

  timestep float = 0.5 fs
    !condition ({?} > 0.0 fs)

  temperature float = 300 K
    !condition ({?} > 0 K)

  pressure float = 1 atm

  steps int = 1000000
    !condition ({?} > 1)

  duration float = ( {?simulation.timestep} * {?simulation.steps} )

  ensemble string = "NPT"
    !options ["NVE", "NVT", "NPT"]

---

Domain-Specific Languages

SciNumTools3 is built around two scientific DSLs.

PUEL — Physical Units Expression Language

A concise language for representing physical quantities, units, dimensions, uncertainties, and arrays.

Examples:

ESU_erg
m2*kg*s-2
kg2*ms3:2*cm
1.346591(30)e27*kg
[2,3,4,5]*km

PUEL powers:

• quantity parsing
• dimensional analysis
• unit conversions
• unit-aware calculations

---

DIPL — Dimensional Input Parameter Language

A declarative language for defining scientific parameters with:

• types
• units
• constraints
• dependencies
• validation rules

This allows scientific applications to maintain a single source of truth for configuration and input validation.

---

Quick Example

from scinumtools3.puq import Quantity
from scinumtools3.dip import DIP

# Unit conversion
length = Quantity("1*m")
length = length.convert("km")

print(length)
# 1e-3*km

# Validated parameters
dip = DIP()

dip.add_string("foo int m")
dip.add_string("foo = 3 km")

env = dip.parse()

print(env.nodes[0])
# 3000 m

---

Documentation

Full documentation, API reference, language specifications, and examples:

https://vrtulka23.github.io/scinumtools3/

Documentation includes:

• Python API reference
• PUEL specification
• DIPL specification
• Tutorials and examples

---

Typical Use Cases

• Scientific computing
• Physics simulations
• Engineering applications
• Data analysis pipelines
• Research software
• Hybrid Python/C++ workflows
• Unit-safe parameter management

---

Contributing

Contributions are welcome.

git clone https://github.com/vrtulka23/scinumtools3.git
cd scinumtools3

Please open an issue or pull request for bug fixes, improvements, or new features.

---

License

SciNumTools3 is released under the MIT License.

See the LICENSE file for details.

---

Links

• PyPI: https://pypi.org/project/scinumtools3/
• Documentation: https://vrtulka23.github.io/scinumtools3/
• GitHub: https://github.com/vrtulka23/scinumtools3
• Issues: https://github.com/vrtulka23/scinumtools3/issues