{"id":44592673,"url":"https://github.com/vrtulka23/scinumtools","last_synced_at":"2026-04-03T00:58:33.914Z","repository":{"id":176823010,"uuid":"657475363","full_name":"vrtulka23/scinumtools","owner":"vrtulka23","description":"Scientific Numerical Tools v2 - Essential tools for numerical scientific calculations, simulations and data analysis. Besides several useful tools, this package is featuring expression solver, physical units, material properties and dimensional input parameter modules.","archived":false,"fork":false,"pushed_at":"2025-07-23T08:18:45.000Z","size":1369,"stargazers_count":7,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-27T11:10:15.419Z","etag":null,"topics":["convertor","dimensions","expression","input-parameters","numerics","physics","python","quantities","scientific-computing","solver","units"],"latest_commit_sha":null,"homepage":"https://vrtulka23.github.io/scinumtools/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vrtulka23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-23T06:29:16.000Z","updated_at":"2025-07-23T08:18:48.000Z","dependencies_parsed_at":"2023-09-22T02:45:16.443Z","dependency_job_id":"6e58c7d4-2b84-4261-8db9-2a8375c541f8","html_url":"https://github.com/vrtulka23/scinumtools","commit_stats":{"total_commits":344,"total_committers":4,"mean_commits":86.0,"dds":0.4215116279069767,"last_synced_commit":"12088f752aa81907928e4b9d0f99480a228f55de"},"previous_names":["vrtulka23/scinumtools"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/vrtulka23/scinumtools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrtulka23%2Fscinumtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrtulka23%2Fscinumtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrtulka23%2Fscinumtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrtulka23%2Fscinumtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vrtulka23","download_url":"https://codeload.github.com/vrtulka23/scinumtools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrtulka23%2Fscinumtools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29439083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T05:24:35.651Z","status":"ssl_error","status_checked_at":"2026-02-14T05:24:34.830Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["convertor","dimensions","expression","input-parameters","numerics","physics","python","quantities","scientific-computing","solver","units"],"created_at":"2026-02-14T07:11:02.960Z","updated_at":"2026-04-03T00:58:33.908Z","avatar_url":"https://github.com/vrtulka23.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI](https://img.shields.io/pypi/v/scinumtools)](https://pypi.org/project/scinumtools)\n[![Supported Python Versions](https://img.shields.io/pypi/pyversions/scinumtools)](https://pypi.org/project/scinumtools/)\n[![PyTest](https://github.com/vrtulka23/scinumtools/actions/workflows/pytest.yml/badge.svg)](https://github.com/vrtulka23/scinumtools/actions/workflows/pytest.yml)\n[![License](https://img.shields.io/github/license/vrtulka23/scinumtools)](https://github.com/vrtulka23/scinumtools/blob/main/LICENSE)\n[![Docs](https://img.shields.io/badge/docs-online-blue)](https://vrtulka23.github.io/scinumtools/)\n\n# SciNumTools v2\n\n![scinumtools](https://raw.githubusercontent.com/vrtulka23/scinumtools/main/docs/source/_static/snt/snt_128.png)\n\nPython package `scinumtools` contains essential tools for scientific and numerical calculations, simulation setup and data analysis. \n\nIt is intedended for computational and simulation-focused scientists and engineers—especially Python users dealing with units, configurations, and complex numerical workflows.\n\n## 🔍 What problem does this solve?\n\nModern scientific and engineering workflows often require combining **symbolic expressions, numerical evaluation, unit handling, and material-specific data** into a single pipeline. In practice, these components are typically handled by separate tools:\n\n* numerical computation (e.g. NumPy/SciPy)\n* symbolic manipulation (e.g. SymPy)\n* unit systems (e.g. Pint)\n* configuration formats such as YAML or JSON\n\nThis fragmentation introduces several recurring problems:\n\n* **Inconsistent representations** between symbolic and numerical stages\n* **Manual and error-prone unit conversions**\n* **Difficult integration of domain data** (e.g. material properties)\n* **Lack of validation for input parameters**, leading to silent errors or physically invalid configurations\n* **Configuration formats lack native support for domain semantics**, requiring external interpretation layers\n\nIn particular, while formats like YAML are widely used for configuring simulations and models, they do not treat **units as first-class entities**. As a result, units are either omitted, encoded as strings, or handled externally, which increases the risk of misinterpretation and inconsistencies. Similarly, parameter definitions are typically not validated beyond basic typing, making it easy to define incomplete, incompatible, or physically meaningless inputs.\n\nThis project addresses these issues by providing a **cohesive framework** that integrates expression parsing, evaluation, unit-aware computation, and parameter validation into a single, consistent environment. The goal is not to replace established numerical libraries, but to **bridge the gap between symbolic definitions, physical units, structured configuration, and domain-specific data** in a lightweight and extensible way.\n\n\u003e [!NOTE]\n\u003e SciNumTools v2 is implemented in Python and targets Python-based workflows. In contrast, [SciNumTools v3](https://github.com/vrtulka23/scinumtools3) is implemented in C++, moving parameter parsing, unit handling, and validation into a compiled core.\n\u003e This allows configurations to be processed directly within performance-critical code and enables integration with HPC systems and other languages without relying on Python.\n\n## ✨ Key features\n\n* **Expression parsing and evaluation**  \n  A flexible system for defining and evaluating mathematical expressions, enabling workflows that combine symbolic structure with numerical execution.\n* **Integrated unit handling**  \n  Built-in support for physical units allows calculations to remain consistent and reduces the risk of unit-related errors during model development.\n* **Validated parameter definitions**  \n  Parameters can be defined with constraints and semantic meaning, enabling early detection of invalid, inconsistent, or incomplete inputs.\n* **Unit-aware configuration support**  \n  Provides a structured alternative to plain YAML-style configurations, where values, units, and constraints are handled explicitly rather than implicitly.\n* **Material property integration**  \n  Enables structured inclusion of material-specific parameters directly into computational workflows, avoiding scattered or hard-coded values.\n* **Domain-oriented design (DIP support)**  \n  Supports domain-informed processing pipelines, allowing users to encode problem-specific logic while maintaining a clear computational structure.\n* **Modular and extensible architecture**  \n  Components such as parsing, evaluation, and data handling are composable and adaptable to different scientific domains.\n* **Lightweight and Python-native**  \n  Designed to integrate easily with existing Python ecosystems without imposing heavy dependencies or complex setup requirements.\n\n## 📚 Documentation\n\nFor more information, see the scinumtools [documentation](https://vrtulka23.github.io/scinumtools/).\nAny comments and suggestions for improvement are heartily welcomed.\n\n## ⚡ Quick start\n\nThe newest release of `scinumtools` is available on [PyPi](https://pypi.org/project/scinumtools/) and can be easily installed using `pip` package manager:\n\n``` python\npip3 install scinumtools\n```\n\nThe package is organized into four main submodules: expression solver, physical units, material properties, and **DIP (Dimensional Input Parameters)**, which provides structured, unit-aware configuration and validation.\n\nThe examples below demonstrate individual components. For complete workflows, see the `examples` directory or test cases in `tests` directory.\n\n### 🧮 Expression Solver\n\nUsing `expression solver` one can quickly build a custom parser that can process numerical, logical and textual expressions. This module is an integral part of other submodules.\nFor more description and examples of [Expression Solver](https://vrtulka23.github.io/scinumtools/solver/index.html), please refer to the documentation. C++ implementation of this module is available in a separate [GitHub repository](https://github.com/vrtulka23/scinumtools3).\n\n``` python\n\u003e\u003e\u003e from scinumtools.solver import *\n\u003e\u003e\u003e class AtomCustom(AtomBase):\n\u003e\u003e\u003e     value: str\n\u003e\u003e\u003e     def __init__(self, value:str):\n\u003e\u003e\u003e         self.value = str(value)\n\u003e\u003e\u003e     def __add__(self, other):\n\u003e\u003e\u003e         return AtomCustom(self.value + other.value)\n\u003e\u003e\u003e     def __gt__(self, other):\n\u003e\u003e\u003e         return AtomCustom(len(self.value) \u003e len(other.value))\n\u003e\u003e\u003e operators = {'add':OperatorAdd,'gt':OperatorGt,'par':OperatorPar}\n\u003e\u003e\u003e steps = [\n\u003e\u003e\u003e     dict(operators=['par'],  otype=Otype.ARGS),\n\u003e\u003e\u003e     dict(operators=['add'],  otype=Otype.BINARY),\n\u003e\u003e\u003e     dict(operators=['gt'],   otype=Otype.BINARY),\n\u003e\u003e\u003e ]\n\u003e\u003e\u003e with ExpressionSolver(AtomCustom, operators, steps) as es:\n\u003e\u003e\u003e     es.solve(\"(limit + 100 km/s) \u003e (limit + 50000000000 km/s)\")\n'False'\n```\n\n### 📏 Physical Units\n\nThis submodule has an aim to make calculations with `physical units` quick and easy. It includes multiple types of units, constants and implements standard numerical operations with physical quantities. Besides that, it features a unit convertor, supports calculations with uncertainties and can be used in combination with third-party libraries like NumPy, or Decimal.\nFor more description and examples of [Physical Units](https://vrtulka23.github.io/scinumtools/units/index.html), please refer to the documentation.\nA C++ implementation of this module [scnt-puq](https://github.com/vrtulka23/scinumtools3) is currently available also as a Python module [pypuq](https://pypi.org/project/pypuq) on PyPi.\n\n``` python\n\u003e\u003e\u003e import numpy as np\n\u003e\u003e\u003e from scinumtools.units import Quantity, Unit\n\u003e\u003e\u003e Quantity(23.34, 'kg*m2/s2').to('erg')     # unit conversions\nQuantity(2.334e+08 erg)\n\u003e\u003e\u003e u = Unit()                                # calculations with units\n\u003e\u003e\u003e 34*u.cm + 53*u.dm  \nQuantity(5.640e+02 cm)\n\u003e\u003e\u003e Quantity(23.34, 'cm', abse=0.03)          # uncertainties\nQuantity(2.3340(30)e+01 cm)\n\u003e\u003e\u003e Quantity(3, 'A').value('dBA')             # logarithmic units\n9.542425094393248\n\u003e\u003e\u003e np.sqrt(Quantity([23,59,20,10], 'm2'))    # arrays and NumPy\nQuantity([4.796 7.681 4.472 3.162] m)\n```\n\n### 🧱 Material Properties\n\nSimulation setups often require atomic and molecular properties of various materials. The core of this submodule, molecular expression solver, is designed to simplify calculations of such properties from a given molecular formula.\nFor more descriptions and examples of [Material Properties](https://vrtulka23.github.io/scinumtools/materials/index.html), please refer to the documentation.\n\n``` python\n\u003e\u003e\u003e from scinumtools.units import Quantity\n\u003e\u003e\u003e from scinumtools.materials import Substance\n\u003e\u003e\u003e s = Substance('H2O', natural=False, mass_density=Quantity(997,'kg/m3'), volume=Quantity(1,'l'))\n\u003e\u003e\u003e s.print()\nComponents:\n\nexpr element  isotope  ionisation  mass[Da]  count  Z  N  e\n   H       H        1           0  1.007825    2.0  1  0  1\n   O       O       16           0 15.994915    1.0  8  8  8\n\nComposite:\n\nTotal mass:     Quantity(1.801e+01 Da)\nTotal number:   3.0\n\nexpr  mass[Da]         Z        N         e       x[%]       X[%]\n   H  2.015650  2.000000 0.000000  2.000000  66.666667  11.191487\n   O 15.994915  8.000000 8.000000  8.000000  33.333333  88.808513\n avg  6.003522  3.333333 2.666667  3.333333  33.333333  33.333333\n sum 18.010565 10.000000 8.000000 10.000000 100.000000 100.000000\n\nMatter:\n\nMass density:   Quantity(9.970e-01 g*cm-3)\nNumber density: Quantity(3.334e+22 cm-3)\nVolume:         Quantity(1.000e+00 l)\nMass:           Quantity(9.970e+02 g)\n\nexpr      n[cm-3]  rho[g/cm3]            N       M[g]\n   H 6.667280e+22    0.111579 6.667280e+25 111.579129\n   O 3.333640e+22    0.885421 3.333640e+25 885.420871\n avg 3.333640e+22    0.332333 3.333640e+25 332.333333\n sum 1.000092e+23    0.997000 1.000092e+26 997.000000\n```\n\n### 🎛️ Dimensional Input Parameters\n\n`DIP` is a serialization language that was designed to collect, manage, convert, document and validate dimensional input parameters used by numerical codes. The main goal of this package is to help developers to focus less on the initialization processes mentioned above and more on actual code development. `DIP` should serve as a quick tool that makes the user interface with the code clear and straightforward. \nFor more description and examples of [DIP](https://vrtulka23.github.io/scinumtools/dip/index.html), please refer to the documentation. A C++ implementation of this library is currently being developed in a [separate GIT repository](https://github.com/vrtulka23/scinumtools3).\n\n``` python\n\u003e\u003e\u003e from scinumtools.dip import DIP, Format\n\u003e\u003e\u003e with DIP() as dip:\n\u003e\u003e\u003e     dip.add_source(\"settings\", 'settings.dip')\n\u003e\u003e\u003e     dip.add_unit(\"length\", 1, \"m\")\n\u003e\u003e\u003e     dip.add_string(\"\"\"\n\u003e\u003e\u003e     box\n\u003e\u003e\u003e       width float = 23 [length]\n\u003e\u003e\u003e       height float = 11.5 cm\n\u003e\u003e\u003e     sphere\n\u003e\u003e\u003e       radius float = {settings?sphere.radius}\n\u003e\u003e\u003e     \"\"\")\n\u003e\u003e\u003e     env = dip.parse()\n\u003e\u003e\u003e     env.data(Format.TUPLE)\n{'box.width': (23.0, '[length]'), 'box.height': (11.5, 'cm'), 'sphere.radius': (34.2, 'mm')}\n```\n\nThe alternative Python module [dipl](https://github.com/vrtulka23/dipl) implements basic loading and dumping functionality of DIP and provides a quick solution for data parsing using DIP.\n\n``` python\n\u003e\u003e\u003e import dipl\n\u003e\u003e\u003e\n\u003e\u003e\u003e dipl.load(\"\"\"\n\u003e\u003e\u003e width float = 173.34 cm\n\u003e\u003e\u003e age int = 24 yr\n\u003e\u003e\u003e \"\"\")\n{'width': (173.34, 'cm'), 'age': (24, 'yr')}\n\u003e\u003e\u003e\n\u003e\u003e\u003e dipl.dump({\n\u003e\u003e\u003e 'children': ['John','Jenny','Jonah'],\n\u003e\u003e\u003e 'car': True\n\u003e\u003e\u003e })\nchildren str[3] = [\"John\",\"Jenny\",\"Jonah\"]\ncar bool = true\n```\n## 🤝 Contributing, Issues \u0026 License\n\nContributions are welcome. If you find a bug, have a feature request, or want to improve the code or documentation, please open an issue or submit a pull request on GitHub.\n\n* **Issues:** Use the issue tracker to report bugs, suggest features, or ask questions\n* **Contributing:** Fork the repository, create a feature branch, and open a pull request with a clear description of your changes\n* **License:** This project is released under the MIT License (see LICENSE file for details)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvrtulka23%2Fscinumtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvrtulka23%2Fscinumtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvrtulka23%2Fscinumtools/lists"}