简体中文 | English
HilbertBalance computes Hilbert-basis solutions for chemical balancing problems.
The repository contains two independent implementations. Each one parses chemical formulas, constructs conservation matrices, and invokes Normaliz on its own. They do not call each other, and neither is a wrapper around the other.
| Directory | Contents | Guide |
|---|---|---|
mathematica/ |
Mathematica package, notebooks, and regression tests | English · 中文 |
python/ |
Python API, CLI, bilingual Web app, and tests | English · 中文 |
The Mathematica implementation provides a .wl package, example notebooks,
and an independent regression suite. It supports interactive symbolic work and
direct inspection of conservation matrices, exact null spaces, Hilbert bases,
coefficient constraints, and reaction-discovery reports.
The Python implementation independently provides the same chemical parsing, matrix construction, and Normaliz computation. It also provides a Python API, command-line program, bilingual Web interface, and HTTP API.
Both implementations require Normaliz. Version 3.11.1 is recommended, and version 3.9.4 is also covered by the regression suite.
For the Python and Web implementation, install Python 3.9 or newer and follow the Python installation guide. For the Mathematica implementation, follow the Mathematica installation guide.
Version 1.5 makes constrained and nonunique balancing the main Web workflow. The bilingual responsive interface uses a default coefficient lower bound of 0, lets users set selected minima to 1 or more, and separates 21 balancing examples from 4 reaction-discovery examples. Chemical subscripts, ionic charges, charge-list guidance, and collapsible discovery filters have also been improved. The Mathematica and Python implementations remain independent.
Input:
H2 + O2 -> H2O
Balanced result:
2H2 + O2 -> 2H2O
Reaction discovery can start from a species pool:
H2, O2, H2O, CO2, C
and finds the three primitive stoichiometric transformations:
O2 + C <-> CO2
2H2 + CO2 <-> 2H2O + C
2H2 + O2 <-> 2H2O
The double arrow is direction-neutral: conservation laws alone cannot decide which direction is physically favorable. A stoichiometric candidate is not a claim that a reaction will occur under experimental conditions.
If HilbertBalance supports your research, please cite:
Zeying Zhang, Guifu Su, Xueqin Zhang, Yuxin Zhao, Zhenghang Zhang, and Shengyuan A. Yang, “Balancing Chemical Equations: From the Perspective of Hilbert Basis,” MATCH Communications in Mathematical and in Computer Chemistry 95 (2026), 589–601.
doi:10.46793/match.95-3.24225 · arXiv:2410.06023
HilbertBalance is distributed under GPL-3.0-or-later. Normaliz is also GPL software. See third-party notices before redistributing a Docker image or binary bundle.