A source-backed Solidity/Foundry project for simulating atoms, nuclides, and narrow chemistry previews on-chain.
- full periodic-table support through
Z = 118 - canonical electron state stored through subshell occupancy to
7p - state-aware nuclide metadata over
ground | m1 | m2 - deterministic one-step decay preview for source-backed radioactive parents
- binary ionic, Lewis-style covalent, and core polyatomic-ion previews
- packed onchain reference blobs generated from JSON source data
- exhaustive generated parity tests plus handwritten behavioral tests
AtomLab lab = AtomLab(atomLabAddress);
uint256 oxygenId = lab.createAtom(8, 8);
AtomLab.AtomDescription memory oxygen = lab.describeAtom(oxygenId);
AtomLab.DecayPreview memory uranium238 = lab.previewNuclideDecay(92, 146);
uint8[] memory atomicNumbers = new uint8[](2);
atomicNumbers[0] = 7;
atomicNumbers[1] = 8;
uint8[] memory counts = new uint8[](2);
counts[0] = 1;
counts[1] = 3;
AtomLab.CompoundPreview memory nitrate = lab.previewCompound(atomicNumbers, counts, -1);A tiny static demo lives in demo/index.html.
It lets you:
- enter
Z,N, and electron count - inspect shell and subshell occupancy
- preview one-step decay when supported
- glance at
NaCl,H2O, andNO3-
From the repo root, start a simple static server:
python3 -m http.serverThen open http://localhost:8000/demo/.
The demo reads directly from the canonical JSON source files in data/, so if you regenerate reference data first, the visualization will reflect the current repo state.
python3 tools/generate_references.py
forge build
forge testRelease-check flow:
python3 tools/generate_references.py
forge fmt --check
forge test
forge build --sizesBefore deploying, make sure the generated artifacts are current:
python3 tools/generate_references.pyThe deploy script then installs:
- packed reference blob contracts from
generated/*.bin ChemistryLabAtomLab
Run:
forge script script/DeployAtomLab.s.sol:DeployAtomLabThe deploy path assumes the generated blobs in generated/ match the JSON source files in data/.
- src/AtomLab.sol: canonical atom, nuclide, and decay surface
- src/ChemistryLab.sol: canonical chemistry preview surface
- src/Subshells.sol: canonical subshell occupancy and shell-summary helpers
- src/ReferenceReader.sol: packed-blob decoding and typed reference lookups
- data/: source-of-truth JSON for elements, nuclides, and chemistry rules
- generated/: generated onchain blob artifacts
- demo/: tiny static demo app
This repo is strong on data discipline, but intentionally narrow in scientific scope:
- not a general chemistry engine
- not a quantum-chemistry solver
- not a reaction engine
- not a full decay-chain simulator
The current chemistry model is preview-only and limited to:
- fixed-charge binary ionic compounds
- a narrow neutral Lewis subset over
H, C, N, O, F, P, S, Cl - a small template-backed polyatomic-ion set:
OH-,NH4+,NO3-,CO3^2-,SO4^2-,PO4^3-