Skip to main content

CelluloseForge

Crystallography-first builder for simulation-ready cellulose and chitin crystals, verified to give the same energy in every MD engine

CI Python 3.11 | 3.12 | 3.13 License: GPL-3.0-or-later Engines Cross-engine agreement

Quick start · Cross-engine validation · Full tutorial · Validation details · Common errors

CelluloseForge overview showing supported cellulose structures and GROMACS force-field outputs

CelluloseForge builds atomistic crystalline polysaccharide structures directly from primary diffraction data: cellulose and chitin crystals, coordinate-only Mannan I crystals, chain-parallel surface slabs, and literature-defined fibrils. It parameterizes them with GLYCAM06j-1 or CHARMM36, or with experimental OpenFF Sage 2.3, OPLS-AA or OPLS-AA-SEI. It then writes them for GROMACS, OpenMM, LAMMPS and (for finite GLYCAM chains) Amber, and checks that every engine evaluates the same energy for the same model.

Release status: CelluloseForge 1.2.0 is the current stable release. Its supported and validated boundaries are intentionally narrower than the long-term project plan. Every supported combination is validated as described in Validation.

✨ Why CelluloseForge?

🔬 The experimental crystal, exactly Cellulose I-alpha, I-beta, II and III-I, and alpha- and beta-chitin, built from primary diffraction data with full triclinic symmetry. The configuration of every stereocentre is checked on every build.
🧱 Any crystalline geometry Periodic bulk crystals, chain-parallel slabs from signed Miller indices, 36-chain fibrils, and I-beta 18- and 24-chain presets and custom row profiles. Chains can be finite or covalently periodic.
⚙️ Five force fields GLYCAM06j-1 (via AmberTools) and CHARMM36 (read directly, no VMD or psfgen), plus experimental OpenFF Sage 2.3, OPLS-AA and OPLS-AA-SEI.
🖥️ Four engines GROMACS, OpenMM, LAMMPS and Amber, each with starting minimization and smoke-test run inputs.
✅ Verified, not just converted Topologies are compared with independent reference tools, and energies term by term across engines, down to 10⁻⁶ (details).
🔁 Reproducible by design Deterministic chain and residue numbering, byte-identical rebuilds, and a machine-readable build report. Every validation result records the commit and software versions that produced it.
🤖 Automation-ready One scriptable CLI and an importable package, with explicit errors and JSON diagnostics for workflow managers and LLM-based agents. Automatic mmCIF output above 99,999 atoms.

🎯 Cross-engine validation: one model, one energy

A topology that every engine accepts can still encode a different energy function: 1-4 scaling, exclusions, switching functions, Ewald conventions and periodic images are each handled differently by different programs. CelluloseForge therefore evaluates the same model in every engine and compares the energies term by term: bonds, angles, torsions, 1-4 pairs, Lennard-Jones, Coulomb and the total.

flowchart LR
    X["Diffraction data<br/>Iα · Iβ · II · IIIᵢ · chitin"] --> M["CelluloseForge model<br/>coordinates + topology"]
    M --> G["GROMACS"]
    M --> O["OpenMM"]
    M --> L["LAMMPS"]
    G --> C{"Term-by-term<br/>energy comparison"}
    O --> C
    L --> C
    C --> V["✅ Same energy function"]
Force field Engines compared Systems Measured agreement
GLYCAM06j-1, CHARMM36 (cellulose) OpenMM vs GROMACS Periodic slabs of all four allomorphs, a finite I-beta slab, and an I-beta bulk crystal Bonded and 1-4: ≤ 8 × 10⁻⁶ relative · total nonbonded: ≤ 1.3 × 10⁻⁴
CHARMM36 (cellulose) LAMMPS vs GROMACS and OpenMM I-beta, I-alpha, II slabs Total ≤ 2.7 × 10⁻⁵ after three documented LAMMPS conventions · bonded and 1-4 within 0.2 kJ/mol
CHARMM36 (chitin) OpenMM and LAMMPS vs GROMACS Alpha and beta, finite and periodic (1 0 0) slabs Bonded within 0.03 kJ/mol · nonbonded totals within 0.7 kJ/mol
OPLS-AA, OPLS-AA-SEI (experimental) OpenMM and LAMMPS vs double-precision GROMACS 36 systems: slabs, bulk crystals and fibrils of every allomorph Bonded, pair and Lennard-Jones terms ≤ 10⁻⁶ · Coulomb and totals ≤ 3 × 10⁻⁶
OpenFF Sage 2.3 (experimental) OpenMM vs GROMACS Slabs, bulk crystals and fibrils of every supported allomorph Within the documented mixed-precision criterion, max(10⁻⁵, 4 ε₃₂ √N)

What the comparisons caught. Files that "just work" would have hidden each of these:

  • 🔎 LAMMPS CHARMM conventions. Three documented offsets (the CHARMM Coulomb constant, constant 1-4 offsets of dihedral_style charmmfsw, and the vfswitch/force-switch shift) account for almost all of a raw 2 × 10⁻⁴ gap (docs/lammps.md).
  • 🔎 An OpenMM Reference-platform discrepancy. For boxes whose third vector is tilted (I-alpha bulk), OpenMM 8.6.1's Reference platform disagreed with an exact nearest-image sum by 0.14--0.40 %, so the CPU platform is used there (validation/measure_openmm_tilted_box.py).
  • 🔎 GROMACS pair-list buffers. grompp rejects boxes only just above twice the cutoff, so CelluloseForge requires a 0.5 Å margin on each side (Periodic box size).
  • 🔎 Coordinate rounding. GRO files round positions to 0.001 nm, which places pairs exactly on the cutoff, so the OPLS comparison uses unrounded coordinates (validation/README.md).

Validation establishes that each model is built and translated correctly. It does not assess how well a force field reproduces cellulose; see What is not validated.

Current support

Structure Polymers and allomorphs Force-field output
Unit cell Cellulose I-alpha, I-beta, II, III-I; alpha- and beta-chitin; Mannan I Coordinate-only: a single cell is narrower than twice any force-field cutoff, so use a periodic bulk crystal for force-field output
Periodic bulk Cellulose I-alpha, I-beta, II, III-I; alpha- and beta-chitin; Mannan I GLYCAM06j-1, CHARMM36 and experimental OpenFF Sage, OPLS-AA and OPLS-AA-SEI (cellulose); CHARMM36 (chitin); coordinate-only (Mannan I)
Slab Chain-parallel faces of the four cellulose allomorphs and of alpha- and beta-chitin GLYCAM06j-1, CHARMM36 and experimental OpenFF Sage, OPLS-AA and OPLS-AA-SEI (cellulose); CHARMM36 (chitin)
36-chain fibril Cellulose I-alpha, I-beta, II GLYCAM06j-1, CHARMM36 and experimental OpenFF Sage, OPLS-AA and OPLS-AA-SEI
18- and 24-chain fibril, custom profiles (main) Cellulose I-beta GLYCAM06j-1, CHARMM36 and experimental OpenFF Sage, OPLS-AA and OPLS-AA-SEI

Simulation engines by force field and chain boundary:

Engine GLYCAM06j-1 CHARMM36 OpenFF Sage (experimental) OPLS-AA, OPLS-AA-SEI (experimental) Status
GROMACS Finite and periodic Finite and periodic Finite and periodic Finite and periodic Released
OpenMM Finite and periodic Finite and periodic Finite and periodic Finite and periodic Released (1.2.0)
LAMMPS Finite and periodic Finite and periodic Not available Finite and periodic Experimental (1.2.0)
Amber Finite only Not available Not available Not available Released (1.2.0)

Native Amber output cannot represent covalently periodic chains because Amber does not minimum-image bonded terms across the box boundary; use GROMACS or OpenMM for those. The software excludes functionalization, native CHARMM/PSF output, and arbitrary branched glycans.

Table of contents

Requirements

Coordinate-only builds

  • Python 3.11, 3.12, or 3.13
  • NumPy 1.26 or newer, below 2.3

GLYCAM/GROMACS builds

In addition to the coordinate-only requirements:

  • AmberTools with tleap
  • GLYCAM06j-1, distributed with AmberTools as leaprc.GLYCAM_06j-1
  • ParmEd
  • GROMACS for preprocessing, minimization, and simulation

AmberTools and ParmEd are not required when --force-field none is used. GROMACS is not required to generate files, but it is required to validate and simulate the generated system.

CHARMM36/GROMACS builds

In addition to the coordinate-only requirements:

  • Internet access for the one-time force-field download, or a local copy of the official pinned archive
  • GROMACS for preprocessing, minimization, and simulation

AmberTools, ParmEd, VMD, and psfgen are not required for CHARMM36 builds. CelluloseForge reads the official GROMACS CHARMM36 files directly.

OpenMM, LAMMPS, OpenFF Sage and OPLS builds

  • OpenMM output (and GLYCAM and CHARMM36 LAMMPS output, which is converted through OpenMM) requires the openmm Python package.
  • OPLS-AA and OPLS-AA-SEI need no extra packages for GROMACS and LAMMPS output; their OpenMM output needs openmm.
  • Experimental OpenFF Sage builds require the separate conda environment in environment-openff.yml (OpenFF Toolkit, Interchange, NAGL and OpenMM). AmberTools is not required.

Installation

Install from PyPI

python -m pip install cellulose-forge
cellulose-forge --help

This installs the coordinate builder and the CHARMM36, OPLS-AA and OPLS-AA-SEI backends, which need only NumPy (CHARMM36 also needs a one-time cellulose-forge forcefield install charmm36). GLYCAM06j-1 additionally needs AmberTools and ParmEd, OpenMM output needs openmm (pip install "cellulose-forge[openmm]"), and OpenFF Sage needs the conda environment described below. To work from the source repository instead, use one of the following.

Coordinate-only installation with uv

git clone https://github.com/askforarun/cellulose-forge.git
cd cellulose-forge
uv sync
uv run cellulose-forge --help

Install uv first if the uv command is unavailable.

Coordinate-only installation with pip

git clone https://github.com/askforarun/cellulose-forge.git
cd cellulose-forge
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
cellulose-forge --help

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

The repository provides an environment.yml containing CelluloseForge, AmberTools, and ParmEd. Create it from the repository root:

git clone https://github.com/askforarun/cellulose-forge.git
cd cellulose-forge
conda env create -f environment.yml
conda activate cellulose-forge
cellulose-forge doctor

AmberTools supplies antechamber, parmchk2, and tleap; the current GLYCAM adapter uses tleap, while ParmEd converts and writes the matched GROMACS topology. The editable package entry in environment.yml installs the local CelluloseForge checkout, so run conda env create from the repository root. GROMACS is not installed by this environment; install it separately when preprocessing or simulation validation is required.

To update an existing environment after the file changes:

conda env update -n cellulose-forge -f environment.yml --prune

Users who only need coordinate generation or CHARMM36 construction may use the lighter uv or pip installation above instead.

Install the CHARMM36 force field

After installing CelluloseForge, download and install the supported official CHARMM36/CGenFF release:

cellulose-forge forcefield install charmm36

When using the uv environment from this repository, run:

uv run cellulose-forge forcefield install charmm36

The installer downloads the pinned February 2026 CHARMM36/CGenFF 5.0 GROMACS archive from the MacKerell Laboratory, verifies its SHA-256 checksum, validates the required files, and installs it under the user data directory. Confirm the exact path with:

cellulose-forge forcefield path charmm36

For an offline machine or compute cluster, first obtain the same official archive and install from the local file:

cellulose-forge forcefield install charmm36 \
  --archive /path/to/charmm36-feb2026_cgenff-5.0.ff.tgz

Set CELLULOSE_FORGE_DATA_DIR before installation if the default ~/.local/share/cellulose-forge location is unsuitable. Normal builds discover this installed release automatically; --charmm-force-field-directory is only needed to override discovery deliberately.

Install the experimental OpenFF Sage environment

conda env create -f environment-openff.yml
conda activate cellulose-forge-openff

The environment pins OpenFF Toolkit, Interchange, NAGL, the NAGL model package, and OpenMM. Without it, --force-field openff exits with an installation message.

Check external tools

Verify the external tools with one diagnostic command:

cellulose-forge doctor

doctor checks Python, NumPy, tleap, ParmEd, OpenMM, LAMMPS, and GROMACS, reports which build modes are ready, and suggests a fix for anything missing. Pass --json for machine-readable output. GROMACS is commonly installed separately using the package manager or module system appropriate to the workstation or cluster. Consult the GROMACS installation guide.

If ParmEd is installed in a different Python environment, pass its interpreter with --parmed-python /path/to/python to both doctor and build. Likewise, a non-default tleap can be selected with --tleap-executable /path/to/tleap, and OpenMM in another interpreter with --openmm-python /path/to/python.

Verify the installation

cellulose-forge --version
cellulose-forge build --help

For a source checkout with development dependencies:

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy src

Quick start

Unit cell

cellulose-forge build \
  --allomorph I-beta \
  --shape unit-cell \
  --output ibeta_unit_cell.pdb

Periodic bulk crystal

The values supplied to --cells are repetitions along the crystallographic a, b, and c axes. Bulk geometry contains complete crystallographic unit cells.

cellulose-forge build \
  --allomorph I-beta \
  --shape bulk \
  --cells 4 4 5 \
  --output ibeta_4x4x5_bulk.pdb

I-beta (110) slab using exact counts

Degree of polymerization is the number of anhydroglucose units in each chain. The current slab builder requires an even value. I-beta (110) slabs also require an even --chains-per-layer so the transverse periodic box contains a complete origin/center-chain lattice repeat. Dimension-based width requests round upward to the next even chain count automatically.

cellulose-forge build \
  --allomorph I-beta \
  --shape slab \
  --face 1 1 0 \
  --layers 4 \
  --chains-per-layer 20 \
  --degree-polymerization 12 \
  --chain-boundary finite \
  --vacuum 30 \
  --output ibeta_110_slab.pdb

Finite-chain simulation boxes require longitudinal padding. The --vacuum option pads the slab-normal direction; it does not separate the chemically capped chain ends from their periodic images. Before using a finite slab with GROMACS, supply at least 3 Å of chain-direction padding with --padding-longitudinal (for example, --padding-longitudinal 20). Without it, terminal atoms can overlap their periodic images and produce catastrophically large nonbonded energies. Values below 12 Å produce a warning because the ends may remain within a typical nonbonded cutoff; validated examples use 12--20 Å. Periodic chains must instead use zero longitudinal padding because their final and first residues are intentionally bonded across the box.

I-beta (110) slab using physical dimensions

Dimensions are specified in angstrom. CelluloseForge rounds upward to complete chains, molecular layers, and cellobiose repeats, and records the realized dimensions in the output metadata.

cellulose-forge build \
  --allomorph I-beta \
  --shape slab \
  --face 1 1 0 \
  --slab-width 120 \
  --slab-thickness 25 \
  --slab-length 60 \
  --chain-boundary periodic \
  --vacuum 30 \
  --output ibeta_110_sized_slab.pdb

Sizing is selected independently for each axis. Supply exactly one option from each pair: --chains-per-layer or --slab-width, --layers or --slab-thickness, and --degree-polymerization or --slab-length. This allows hybrid requests such as four exact layers with minimum 40 Å width and 40 Å chain length:

cellulose-forge build \
  --allomorph I-beta --shape slab --face 1 1 0 \
  --layers 4 --slab-width 40 --slab-length 40 \
  --chain-boundary finite --vacuum 30 \
  --output ibeta_110_hybrid.pdb

Fibril cross-sections

cellulose-forge build \
  --allomorph I-beta \
  --shape fibril \
  --fibril-model 36-chain \
  --degree-polymerization 12 \
  --chain-boundary periodic \
  --vacuum 30 \
  --output ibeta_36chain_dp12.pdb

The preset is an explicit published chain arrangement, not an ideal regular hexagon. Cellulose III-I has no supported 36-chain reference preset.

The development branch also provides I-beta 18- and 24-chain profiles:

cellulose-forge build \
  --allomorph I-beta --shape fibril \
  --fibril-model 18-chain \
  --degree-polymerization 12 --chain-boundary periodic \
  --vacuum 30 --output ibeta_18chain_dp12.pdb

The 18-chain profile is 2,3,4,4,3,2; the 24-chain profile is 3,4,5,5,4,3. Rows are listed from low to high Cartesian z. A custom profile within the validated I-beta 36-chain lattice envelope can be supplied directly:

cellulose-forge build \
  --allomorph I-beta --shape fibril \
  --fibril-profile 1,2,3,2,1 \
  --degree-polymerization 12 --chain-boundary periodic \
  --vacuum 30 --output ibeta_custom_dp12.pdb

The 18-/24-chain and custom-profile paths currently support I-beta only. A custom row list is a geometric request and is not described as a literature-defined fibril unless its exact arrangement has a cited source.

For independent transverse box control, use --padding-x for Cartesian x and --padding-y for the second transverse direction, Cartesian z. Both values are total padding and are divided equally between opposite sides. For a finite fibril, --padding-longitudinal controls total padding beyond the chain ends along the chain axis:

cellulose-forge build \
  --allomorph I-beta \
  --shape fibril \
  --fibril-model 36-chain \
  --degree-polymerization 12 \
  --chain-boundary finite \
  --padding-x 30 \
  --padding-y 40 \
  --padding-longitudinal 20 \
  --output ibeta_36chain_finite_padded.pdb

For periodic chains, the y box length is fixed by the crystallographic repeat; nonzero --padding-longitudinal is rejected because it would break the covalent bond across the boundary. --vacuum N remains a shorthand that applies N total padding to both transverse directions unless the corresponding option overrides it. The historical --padding-z spelling is accepted as a deprecated alias.

Chitin and mannan

Chitin

--polymer chitin builds alpha- and beta-chitin unit cells, periodic bulk crystals, and chain-parallel slabs:

cellulose-forge build --polymer chitin --allomorph alpha \
  --shape bulk --cells 4 2 3 --output alpha_chitin.pdb

The alpha-chitin structure (P212121, 293 K) is from Sikorski, Hori and Wada, Biomacromolecules 2009, 10, 1100-1105 (doi:10.1021/bm801251e); its disordered hydroxymethyl group is selected with --o6-conformation major|minor. Anhydrous beta-chitin (P21, setting P 1 1 21, 293 K) is from Nishiyama, Noishiki and Wada, Macromolecules 2011, 44, 950-957 (doi:10.1021/ma102240r). Residues are written as NAG, and every residue's C1-C5 configuration is checked against N-acetyl-beta-D-glucosamine.

Chitin slabs use the same general reciprocal-lattice construction as cellulose, for any (h k 0) face and finite or periodic chains:

cellulose-forge build --polymer chitin --allomorph beta --shape slab \
  --face 1 0 0 --layers 3 --chains-per-layer 4 --degree-polymerization 6 \
  --chain-boundary periodic --vacuum 20 --output beta_chitin_100.pdb

--force-field charmm36 builds chitin with the CHARMM36 BGLCNA residue, linked by the 14bb patch, for GROMACS and, with --md-engine openmm or --md-engine lammps, for OpenMM and LAMMPS:

cellulose-forge build --polymer chitin --allomorph beta --shape slab \
  --face 1 0 0 --layers 3 --chains-per-layer 4 --degree-polymerization 6 \
  --chain-boundary periodic --vacuum 20 --force-field charmm36 --output beta_chitin_100

The output directory contains chitin_charmm36.itp (cellulose keeps cellulose_charmm36.itp), system.top, structure.gro, the run inputs, and a local charmm36.ff. Each residue carries the two acetyl impropers. Finite chains use free-sugar termini: the reducing end keeps O1/HO1 (-0.18 e) and the non-reducing end keeps HO4 (+0.18 e). Position restraints for chitin use the POSRES_CHITIN define. GLYCAM/Amber, OpenFF Sage and fibrils are not yet available for chitin.

Mannan

--polymer mannan currently builds coordinate-only Mannan I unit cells and periodic bulk crystals:

cellulose-forge build --polymer mannan --allomorph I \
  --shape bulk --cells 4 4 5 --output mannan_i.pdb

The model uses the orthorhombic P212121 cell (a = 8.92, b = 7.21, c = 10.27 A) and antiparallel two-fold helices of Chanzy et al., Macromolecules 1987, 20, 2407-2413 (doi:10.1021/ma00176a014). Table I supplies the non-hydroxyl coordinates and the paper supplies the chain transforms. The tabulated O1 duplicates the screw-related O4 glycosidic oxygen and is stored once as O4. Hydroxyl hydrogens, absent from the table, are modelled with tetrahedral C-O-H geometry toward acceptors in the reported hydrogen-bond network and are identified as modelled in the package-data provenance and build report. Their coupled torsions avoid periodic hydrogen clashes while preserving the primary heavy atoms. The Table I O3...O5 contact is 2.385 A, shorter than later refinements; any future force-field use must therefore begin with a restrained relaxation of the modelled hydrogens.

Slabs and force-field output remain disabled for mannan until separately implemented and validated. Mannan II is not yet enabled because its hydrated four-chain atomic model and water sites must first be recovered and audited against the primary structural source; it will not be inferred from Mannan I.

Force-field workflows

GLYCAM and GROMACS

Select --force-field glycam and provide an output directory instead of a coordinate filename:

cellulose-forge build \
  --allomorph I-beta \
  --shape fibril \
  --fibril-model 36-chain \
  --degree-polymerization 12 \
  --chain-boundary periodic \
  --vacuum 30 \
  --force-field glycam \
  --output ibeta_fibril

CelluloseForge asks tleap to construct one GLYCAM chain, converts that reference with ParmEd, maps the crystallographic coordinates into GLYCAM atom order, and repeats the topology for the generated chains.

For cellulose II, the diffraction dataset does not contain hydroxyl-hydrogen coordinates. GLYCAM and OpenFF output construct HO2, HO3, and HO6 on an exact tetrahedral cone (0.96 A O-H, 108.5 degree C-O-H). Hydrogens are placed class by class (HO3, HO2, HO6) so that equivalent hydroxyls are treated identically: HO3 takes the intrachain O3-H...O5 bond present in every cellulose allomorph, and the others take the clash-free torsion with the best geometric hydrogen bond, otherwise the aligned force-field torsion. The experimental heavy-atom coordinates remain unchanged; minimize before dynamics. Origin and center chains are mapped in opposite residue directions to preserve the allomorph's antiparallel connectivity. This construction is recorded in build_report.json.

Preprocess and minimize the generated system with GROMACS:

gmx grompp \
  -f ibeta_fibril/minim.mdp \
  -c ibeta_fibril/structure.gro \
  -p ibeta_fibril/system.top \
  -o ibeta_fibril/minim.tpr

gmx mdrun -deffnm ibeta_fibril/minim

CHARMM36

Install the pinned official February 2026 CHARMM36/CGenFF 5.0 GROMACS port once:

cellulose-forge forcefield install charmm36

Build a finite cellulose I-beta (110) slab with native CHARMM36/GROMACS topology:

cellulose-forge build \
  --allomorph I-beta \
  --shape slab \
  --face 1 1 0 \
  --layers 4 \
  --chains-per-layer 20 \
  --degree-polymerization 12 \
  --chain-boundary finite \
  --vacuum 30 \
  --padding-longitudinal 20 \
  --force-field charmm36 \
  --output ibeta_110_charmm36

The output directory contains structure.gro, structure.pdb (or mmCIF for large systems), cellulose_charmm36.itp, system.top, minim.mdp, nvt.mdp, the pinned local force-field files, and build_report.json. Preprocess it with:

gmx grompp \
  -f ibeta_110_charmm36/minim.mdp \
  -c ibeta_110_charmm36/structure.gro \
  -p ibeta_110_charmm36/system.top \
  -o ibeta_110_charmm36/minim.tpr

gmx mdrun -deffnm ibeta_110_charmm36/minim

The installer verifies the archive checksum and records a stable local release; upstream updates are adopted only through an explicit CelluloseForge update. CelluloseForge reads BGLC from the installed force field, applies finite or cyclic 14bb linkages, and writes matched GRO/ITP/TOP output directly without a reference-chain ITP, VMD, or psfgen. See the full tutorial for finite and periodic examples and docs/charmm36.md for the implementation.

Experimental OpenFF Sage

CelluloseForge includes an optional, experimental OpenFF Sage 2.3 backend for finite and periodic cellulose slabs and fibrils and periodic bulk crystals, with GROMACS and OpenMM output in the same layout as GLYCAM and CHARMM36. It constructs the molecular graph directly and assigns NAGL charges; AmberTools is not required. Model construction is validated, but force-field accuracy for cellulose has not been assessed.

conda activate cellulose-forge-openff
cellulose-forge build \
  --allomorph I-beta --shape fibril --fibril-model 36-chain \
  --degree-polymerization 6 --chain-boundary periodic --vacuum 20 \
  --force-field openff --md-engine gromacs --md-engine openmm \
  --output openff_ibeta_fibril

Chitin, mannan, Amber, LAMMPS, unit cells, finite bulk crystals, and position restraints are rejected for OpenFF. See docs/openff.md for the precise scope.

Experimental OPLS-AA and OPLS-AA-SEI

--force-field opls-aa applies the OPLS-AA carbohydrate parameters of Damm et al. (1997) and --force-field opls-aa-sei the OPLS-AA-SEI refinement of Kony et al. (2002), which reparameterizes several torsions and divides 1-5 electrostatics within each residue by 1.26 (1-6 hydroxymethyl/C4-hydroxyl pairs by 1.22). Both cover finite and periodic cellulose slabs and fibrils and periodic bulk crystals, with GROMACS, OpenMM and LAMMPS output, and need no external parameter files. The topologies are validated against the published parameters and across the three engines; force-field accuracy for cellulose has not been assessed.

cellulose-forge build \
  --allomorph I-beta --shape slab --face 1 1 0 \
  --layers 3 --chains-per-layer 4 --degree-polymerization 6 \
  --chain-boundary periodic --vacuum 30 \
  --force-field opls-aa-sei \
  --md-engine gromacs --md-engine openmm --md-engine lammps \
  --output opls_sei_ibeta_slab

In LAMMPS the SEI-scaled pairs are tabulated pseudo-bonds, so their energy appears in ebond. Chitin, mannan, Amber, unit cells, finite bulk crystals and position restraints are rejected. See docs/opls.md for parameter sources, the three interpretations needed to apply the monosaccharide parameters to cellulose, and each engine's representation.

Selective chain position restraints

GLYCAM and CHARMM36 builds can apply GROMACS position restraints to the heavy atoms of selected chains. Hydrogens remain unrestrained. Chain and transverse-layer IDs are deterministic, one-based identifiers reported in build_report.json. Select explicit chains with --restrain-chains or complete layers with --restrain-layers. The two selectors are mutually exclusive. For example, this one-sided four-layer slab restrains the heavy atoms in layers 1 and 2 while layers 3 and 4 remain fully flexible:

cellulose-forge build \
  --allomorph I-beta \
  --shape slab \
  --face 1 1 0 \
  --layers 4 \
  --chains-per-layer 20 \
  --degree-polymerization 12 \
  --chain-boundary finite \
  --vacuum 30 \
  --padding-longitudinal 20 \
  --force-field glycam \
  --restrain-layers 1 2 \
  --restraint-force 1000 1000 1000 \
  --output restrained_4layer_slab

Slab and fibril layers are numbered from low to high Cartesian z. Fibril cross-sections are displayed with the documented 90-degree counterclockwise rotation, and their layers follow the explicit bottom-to-top rows of the literature-defined preset. Within each fibril layer, chain IDs increase from low to high Cartesian x. The generated topology separates free and restrained chains while preserving the coordinate-to-topology order. The build report records the layer-to-chain expansion and maps each selected chain ID to its GROMACS molecule index and global atom range. Its atom_selection field records that only heavy atoms in those chains are restrained.

The generated minim.mdp and nvt.mdp contain a commented define line. Uncomment it, or add the define to your own MDP file, to enable the restraints:

define = -DPOSRES_CELLULOSE

Then pass the reference coordinates with gmx grompp -r:

gmx grompp \
  -f restrained_4layer_slab/nvt.mdp \
  -c restrained_4layer_slab/structure.gro \
  -r restrained_4layer_slab/structure.gro \
  -p restrained_4layer_slab/system.top \
  -o restrained_4layer_slab/nvt.tpr

Omitting the define disables the restraints without requiring a new structure or topology. Chitin uses -DPOSRES_CHITIN. The three values supplied to --restraint-force are the x, y, and z force constants in kJ mol$^{-1}$ nm$^{-2}$.

Output files and run inputs

Coordinate-only mode

The filename extension selects PDB or PDBx/mmCIF. Every coordinate-only build also writes a sibling <structure>.build_report.json containing the interpreted geometry, chain count, derived degree of polymerization, and actual coordinate filename:

structure.pdb
structure.build_report.json
structure.cif
structure.mmcif

When physical slab dimensions are requested, the report records both the requested and realized dimensions in geometry_annotations. The reported DP is the even number of anhydroglucose units obtained by rounding the requested chain-direction length upward to complete cellobiose repeats.

Force-field mode

ibeta_fibril/
├── structure.pdb       # or structure.cif for more than 99,999 crystal atoms
├── structure.gro       # GROMACS coordinates            (--md-engine gromacs)
├── system.top          # standalone GROMACS topology
├── minim.mdp           # GROMACS minimization input
├── nvt.mdp             # GROMACS 1 ps NVT smoke test
├── system.xml          # OpenMM system                  (--md-engine openmm)
├── state.xml           # OpenMM starting state
├── topology.cif        # OpenMM topology and coordinates
├── run_openmm.py       # configurable OpenMM runner
├── system.data         # LAMMPS data file               (--md-engine lammps)
├── in.cellulose        # LAMMPS input (in.chitin for chitin)
├── structure.prmtop    # Amber topology                 (--md-engine amber)
├── structure.inpcrd    # Amber coordinates
├── min.in              # Amber minimization input
├── nvt.in              # Amber 1 ps NVT smoke test
└── build_report.json   # inputs, provenance, counts, and generated files

Only the files for the selected engines are written.

Native Amber files describe the complete multi-chain system and use the same mapped coordinates, periodic box, GLYCAM charges, and bonded topology as the GROMACS output; they are available for finite GLYCAM chains only. See docs/amber.md.

OpenMM output needs only OpenMM to run (pip install 'cellulose-forge[openmm]' or environment.yml). For periodic chains, every bonded force and the nonbonded 1--4 exceptions use periodic boundary conditions. OpenMM barostats move molecules rigidly, so periodic chains are run with the chain axis fixed; use GROMACS for fully anisotropic NPT of periodic crystals. See docs/openmm.md.

Experimental LAMMPS output (--md-engine lammps) writes system.data and in.cellulose; generation uses OpenMM as a topology parser but does not require GROMACS. The generated input performs a run 0 energy check, not a production simulation. Position restraints are not yet implemented. See docs/lammps.md.

Existing scripts using --topology-format gromacs|amber|both remain valid but emit a deprecation warning. New workflows should use --md-engine.

Nonbonded settings in the generated inputs

Force field GROMACS (minim.mdp, nvt.mdp) OpenMM (system.xml) LAMMPS Amber (min.in, nvt.in)
GLYCAM06j-1 PME, plain 1.0 nm cut-off PME, 1.0 nm cut-off lj/cut/coul/long 10.0 cut = 10.0
CHARMM36 PME, plain 1.0 nm cut-off (smoke test only, labelled in the file) PME, 1.0 nm cut-off lj/charmmfsw/coul/long 10.0 12.0 (official force switch) not available
OpenFF Sage PME 0.9 nm; Lennard-Jones potential switch 0.8--0.9 nm Sage switch 0.8--0.9 nm, PME 0.9 nm not available not available
OPLS-AA, OPLS-AA-SEI PME, plain 1.0 nm cut-off PME, 1.0 nm cut-off; geometric-mixing Lennard-Jones in a CustomNonbondedForce lj/cut/coul/long 10.0, mix geometric; SEI pairs as tabulated pseudo-bonds not available

Long-range dispersion correction follows one rule in every engine: GLYCAM06, OPLS-AA and Sage use it for bulk crystals and unit cells only, CHARMM36 never uses it, and slabs and fibrils never use it. It appears as DispCorr in GROMACS, as the flags of both nonbonded forces in OpenMM, as pair_modify tail in LAMMPS, and as vdwmeth in Amber.

The generated inputs are smoke-test protocols, not production settings. OpenMM files use ewaldErrorTolerance = 5e-4; GROMACS files use the default fourierspacing = 0.12 nm and PME order 4. For CHARMM36, GROMACS and OpenMM use a plain 1.0 nm cut-off because OpenMM cannot reproduce the CHARMM force switch and the two engines were validated with matching settings; production CHARMM36 runs normally use vdw-modifier = force-switch, rvdw-switch = 1.0 and rvdw = rcoulomb = 1.2, which requires every box height above 2.4 nm. For finite chains, ensure that the periodic box provides sufficient separation between chain ends.

Command reference

cellulose-forge build --allomorph ALLOMORPH --shape SHAPE [OPTIONS] --output PATH
Option Values or units Meaning
--polymer cellulose, chitin, mannan Crystalline polysaccharide (default cellulose)
--allomorph cellulose I-alpha, I-beta, II, III-I; chitin alpha, beta; mannan I Crystal allomorph
--o6-conformation major, minor Alpha-chitin hydroxymethyl position
--shape unit-cell, bulk, slab, fibril Structure type
--cells NA NB NC positive integers Bulk repetitions along a, b, and c
--face H K L signed integers Slab Miller index; the index along the allomorph's chain axis must be zero
--layers positive integer Complete molecular layers in an exact-count slab
--chains-per-layer positive integer Chains in each exact-count slab layer
--degree-polymerization positive even integer Residues per chain
--slab-width angstrom Minimum transverse width
--slab-thickness angstrom Minimum thickness normal to the surface
--slab-length angstrom Minimum chain-direction length
--fibril-model 18-chain, 24-chain, 36-chain Named fibril preset; 18/24 currently require I-beta
--fibril-profile comma-separated positive integers Custom I-beta row counts from low to high Cartesian z
--chain-boundary finite, periodic Terminal groups or a covalent bond across the chain boundary
--vacuum angstrom Total transverse vacuum padding
--padding-x angstrom Total fibril x padding; overrides --vacuum for x
--padding-y angstrom Total fibril padding in its second transverse direction (Cartesian z); overrides --vacuum
--padding-longitudinal angstrom Total chain-axis padding; periodic chains require zero
--padding-z angstrom Deprecated alias for --padding-longitudinal
--force-field none, glycam, charmm36, openff, opls-aa, opls-aa-sei Coordinate-only construction or molecular-mechanics parameter set; openff, opls-aa and opls-aa-sei are experimental
--md-engine gromacs, amber, openmm, lammps Target engine; repeat for multiple outputs
--topology-format gromacs, amber, both Deprecated compatibility alias for GLYCAM builds
--tleap-executable executable path tleap used for GLYCAM builds
--parmed-python Python path Interpreter containing ParmEd
--openmm-python Python path Interpreter containing OpenMM
--charmm-template ITP path Optional periodic reference topology for regression studies
--charmm-force-field-directory directory Optional override for the installed CHARMM36 release
--restrain-chains one or more IDs Restrain selected deterministic chain IDs
--restrain-layers one or more IDs Restrain geometry-defined transverse layers
--restraint-force FX FY FZ Position-restraint force constants in kJ mol$^{-1}$ nm$^{-2}$
--output file or directory Coordinate file for none; directory for force-field builds

Run cellulose-forge build --help for the authoritative parser help.

Large systems

PDB atom serial numbers are limited to five columns. If a requested PDB would contain more than 99,999 atoms, CelluloseForge writes a sibling .cif file and prints its path. It never silently truncates or wraps a PDB.

For a parameterized system exceeding this limit:

  • use structure.cif for visualization and unambiguous identifiers;
  • use structure.gro with system.top for GROMACS;
  • use the compiled .tpr for simulation.

GRO atom and residue identifiers are also five-column fields and therefore wrap for very large systems. GROMACS reads the coordinate records in topology order, but mmCIF should be used when unique human-readable identifiers matter.

Scientific conventions

Slab orientation

Slabs use a simulation-oriented Cartesian frame compatible with GROMACS semi-isotropic pressure coupling:

  • transverse surface direction: x;
  • cellulose chain direction: -y;
  • outward surface normal and vacuum direction: -z.

The requested face is the low-z surface. Layers increase toward high z, and chains within a layer are ordered from low x to high x.

Chain identifiers

Chains have stable one-based numeric identifiers. PDB one-character chain labels are reused after 62 chains, while the segment field records C001, C002, and so on. Use numeric chain mappings or mmCIF identifiers for restraints and analysis of large systems.

Slab faces

Additional chain-parallel faces beyond the validated reference faces are generated by the same reciprocal-lattice, whole-chain construction and should be checked for the intended application. Following the Cellulose-Builder convention for I-beta, (100) and (010) expose origin-chain layers, whereas (200) and (020) expose center-chain layers halfway through the unit cell.

Periodic box size

Every force-field build requires each perpendicular box height to exceed twice the GROMACS/OpenMM nonbonded cutoff plus a 0.5 Å pair-list buffer on each side: 21 Å for GLYCAM06, CHARMM36, OPLS-AA and OPLS-AA-SEI (1.0 nm cutoff) and 19 Å for OpenFF Sage (0.9 nm). GROMACS and OpenMM evaluate pairs by the minimum-image convention. The 0.5 Å margin is a conservative CelluloseForge policy, not a general pair-list requirement: the Verlet buffer GROMACS adds before its own box check depends on the MD settings (temperature, time step, nstlist, verlet-buffer-tolerance). With the generated inputs a 1.0 nm cutoff was rejected on a 20.62 Å box and accepted on 21.04 Å; production settings with longer time steps or neighbour-list intervals may need larger boxes. LAMMPS replicates ghost atoms for every periodic image and has no such limit, but the same rule applies to every build so that all engines' files remain usable. A slab or fibril with less transverse vacuum than the longest interaction range (10 Å GLYCAM and OPLS, 12 Å CHARMM36, 9 Å Sage) produces a warning, because the vacuum-based choice to disable dispersion correction then no longer holds.

Validation

Validation establishes that CelluloseForge builds each force-field model correctly and that the generated systems run. It does not assess how well a force field reproduces the structure or mechanics of cellulose crystals; that requires long simulations compared with experiment. Scripts are in validation/ and results in validation/results/; results files record the CelluloseForge commit and software versions used.

Crystallography and stereochemistry

  • Unit cells: crystallographic cell, symmetry, and atom counts are tested for every allomorph.
  • Geometry: right-handed slab orientation transforms are enforced, and stereocentre preservation is tested for supported allomorphs and reference faces. Every build checks the configuration of each residue (D-glucose for cellulose, N-acetyl-D-glucosamine at C1--C5 for chitin, beta-D-mannose at all five ring stereocentres for Mannan I).
  • Chitin slabs: beta (100), (010), (110) and alpha (100), (010), (110) are tested for chain directions, periodic O4-C1 bonds, flat layers, an exact lattice repeat across the periodic box, and no interchain clashes. Reference faces for chitin force-field validation have not yet been selected from the literature.
  • Mannan I: covalent distances, periodic O4-C1 linkages, antiparallel-chain packing, and interchain clashes are tested.
  • Cellulose II modelled hydrogens: validate_cellulose_ii_hydroxyls.py records the hydrogen-bond network per chain. Every modelled hydroxyl hydrogen-bonds, identically in equivalent residues, and the network matches the published cellulose II scheme (intrachain O3-H...O5 in both chains; intermolecular O2-H...O6, O6-H...O6 and intersheet O2-H...O2), apart from the OH2/OH6 directions the literature reports as least certain.

Topology against reference tools

  • GLYCAM06j-1: each chain is generated by tleap and converted by ParmEd; the multi-chain topology repeats that reference exactly.
  • CHARMM36 cellulose: generated finite and periodic topologies match independent psfgen builds from the official CHARMM files, including all atom types, charges, and 2,883 bond, pair, angle, and dihedral interactions in the finite reference (docs/charmm36.md).
  • CHARMM36 chitin: the finite DP6 topology matches an independent psfgen build from top_all36_carb.rtf (validate_chitin_charmm36_reference.py), covering atom properties, terminal composition, interaction graphs, impropers, 1-4 pairs, and function types. psfgen was used only to build the reference; CelluloseForge does not need it.

GROMACS workflows

  • Finite and periodic GLYCAM06j-1 and CHARMM36 slabs for I-alpha (010), I-beta (110), II (110), and III-I (110), and GLYCAM06j-1 and CHARMM36 periodic bulk crystals of all four allomorphs, pass gmx grompp with zero warnings, minimization, and a 1 ps NVT smoke test.
  • 36-chain fibrils: the geometry presets are tested, and periodic GLYCAM06j-1 and finite and periodic CHARMM36 GROMACS workflows are validated.
  • I-beta 18-chain finite and 24-chain periodic presets pass GROMACS preprocessing with GLYCAM and CHARMM36.
  • Chitin CHARMM36: alpha and beta periodic bulk, periodic (1 0 0) slabs, and finite (1 0 0) slabs pass gmx grompp, minimization, and a 1 ps NVT smoke test (validate_chitin_charmm36_gromacs.py).
  • Large systems: a finite I-beta (110) slab with 100,800 crystallographic atoms was mapped to 102,000 GLYCAM atoms and passed GROMACS 2024.2 gmx grompp with PME, zero warnings, and no -maxwarn allowance.

Cross-engine energy agreement

  • OpenMM against GROMACS (validate_openmm_engine.py): for all four cellulose allomorphs and both force fields, bonded and 1--4 energies agree within 8 × 10^-6 relative and total nonbonded energies within 1.3 × 10^-4 with matching settings.
  • LAMMPS against GROMACS and OpenMM (validate_charmm36_engines.py, docs/lammps.md): the raw 1.8--2.5 × 10^-4 total-potential gap for CHARMM36 cellulose slabs is almost entirely three documented LAMMPS conventions (the CHARMM Coulomb constant, constant 1-4 offsets of dihedral_style charmmfsw, and the constant shift between CHARMM vfswitch and GROMACS force-switch). After removing them, total potentials agree within 2.7 × 10^-5 and every bonded and 1-4 term within 0.2 kJ/mol.
  • Chitin CHARMM36: OpenMM and LAMMPS energies were compared with GROMACS term by term for alpha and beta, finite and periodic (1 0 0) slabs; bonded terms agree within 0.03 kJ/mol and nonbonded totals within 0.7 kJ/mol. LAMMPS impropers use improper_style harmonic with K = k/2.
  • Amber: generated files reload in ParmEd with the expected atom count, residue count, total charge, and box, and complete a sander minimization (docs/amber.md).

Experimental OpenFF Sage

Model construction is validated in validation/OPENFF_EXPERIMENTAL_REPORT.md:

  • the molecular graph matches PubChem stereochemistry, and every C1--C5 centre is checked by signed parity at build time, with inversion and mirror negative controls in the validators;
  • periodic chains receive complete, translationally identical bonded terms across the boundary, and NAGL charges are neutral and equivalent across residues;
  • slabs, bulk crystals, and fibrils of every supported allomorph pass term-by-term OpenMM/GROMACS energy comparison and GROMACS and OpenMM minimization and 1 ps NVT; the exact shipped files are run as well.

Energies are accepted within an empirical mixed-precision criterion, max(1e-5, 4 eps32 sqrt(N)) relative, documented with its measured evidence (measure_openff_mixed_precision.py). These checks do not establish the accuracy of OpenFF Sage for crystalline cellulose.

Experimental OPLS-AA and OPLS-AA-SEI

validation/validate_opls_cellulose.py covers finite and periodic slabs and 36-chain fibrils and periodic bulk crystals of every supported allomorph, for both variants (validation/results/opls_cellulose_matrix.json):

  • the Kony et al. Table 3 OPLS-AA torsions and every explicit bond and angle parameter equal the installed GROMACS oplsaa.ff;
  • torsion, 1-4 and SEI-pair energies recomputed in NumPy agree with double-precision GROMACS, and the OPLS-AA-SEI minus OPLS-AA nonbonded energy equals the analytic effect of the scaling;
  • OpenMM and LAMMPS agree with double-precision GROMACS term by term (bonds, angles, torsions, 1-4 and SEI pairs, Lennard-Jones) within 10^-6 relative, and in Coulomb and total energy within 10^-5 of the total potential, on identical, unrounded coordinates; the LAMMPS SEI tables are compared separately with an independent recomputation of the SEI pairs;
  • GROMACS (grompp -maxwarn 0, minimization, 1 ps NVT), the generated OpenMM runner (minimization and 1 ps) and the generated LAMMPS input all run.

These checks do not establish the accuracy of either force field for crystalline cellulose.

What is not validated

  • Force-field accuracy against experiment (cell parameters, hydrogen-bond networks, mechanics) for any force field.
  • Long-time stability: the smoke tests run 1 ps.
  • Production protocols: the generated run inputs are starting points.

Common errors

the periodic box must exceed N angstrom (twice the ... nonbonded cutoff plus a 0.5 angstrom pair-list buffer on each side) in every direction : The box is too small for the force field's cutoff in at least one direction (21 Å for GLYCAM06, CHARMM36, OPLS-AA and OPLS-AA-SEI; 19 Å for OpenFF Sage). Increase --cells for bulk crystals, or --chains-per-layer, --layers, --degree-polymerization, the padding, or --vacuum for slabs and fibrils.

finite force-field chains require at least 3 angstrom longitudinal padding : Finite chains need space between chain ends and their periodic images. Add --padding-longitudinal 12 or more. Values between 3 and 12 Å are accepted with a warning.

finite-chain periodic-image clash: chain ... are ... angstrom apart : Chain ends overlap their periodic images. Increase --padding-longitudinal.

--padding-longitudinal must be zero with --chain-boundary periodic : Periodic chains are bonded across the box; chain-direction padding would break that bond. Remove the option or use --chain-boundary finite.

Warning: the slab|fibril has less than N angstrom of transverse vacuum : Periodic images of the slab or fibril are within the interaction range, so the system is no longer an isolated surface and the vacuum-based choice to disable dispersion correction no longer holds. Use --vacuum 20 or more.

native Amber output currently supports finite chains only : Amber cannot minimum-image a bonded term across the chain boundary. Use --chain-boundary finite with longitudinal padding, or GROMACS or OpenMM for periodic chains.

--output must be a directory when --force-field glycam|charmm36 is selected : Force-field builds write several files. Give a directory name without a file extension.

--chain-boundary finite|periodic is required ... : Slabs, fibrils, and force-field builds need an explicit chain boundary. GLYCAM bulk crystals and unit cells require --chain-boundary periodic.

tleap executable was not found / Python executable for ParmEd was not found : GLYCAM builds need AmberTools and ParmEd. Activate the environment.yml environment, or pass --tleap-executable and --parmed-python. Run cellulose-forge doctor to check every tool.

CHARMM36 ... is not installed; run 'cellulose-forge forcefield install charmm36' : Install the pinned force field once, or use --archive with a local copy on offline machines.

OpenFF Sage support requires the optional OpenFF environment : Create and activate environment-openff.yml.

experimental OpenFF Sage support is limited to cellulose / experimental OpenFF supports --md-engine gromacs and openmm only : OpenFF currently covers cellulose slabs, fibrils, and periodic bulk crystals with GROMACS or OpenMM output. Use GLYCAM06 or CHARMM36 for other combinations.

experimental OPLS-AA support is limited to cellulose / experimental OPLS-AA and OPLS-AA-SEI support --md-engine gromacs, openmm, and lammps : OPLS-AA and OPLS-AA-SEI cover cellulose slabs, fibrils, and periodic bulk crystals with GROMACS, OpenMM or LAMMPS output (no Amber, no restraints).

mannan force-field output is not implemented; use --force-field none : Mannan I is coordinate-only.

chitin supports --force-field none or charmm36 : GLYCAM, Amber, and OpenFF topologies are not implemented for chitin.

... requires an even degree of polymerization : Slabs and 36-chain fibrils are built from complete cellobiose repeats; use an even --degree-polymerization.

GROMACS: The cut-off length is longer than half the shortest box vector : This occurs if a generated MDP file is edited to a longer cutoff, for example the CHARMM36 production force switch (1.2 nm), on a box built for 1.0 nm. Build a larger system so every box height exceeds 2.4 nm.

A PDB was not written and a .cif file appeared instead : Not an error. PDB files cannot hold more than 99,999 atoms, so CelluloseForge writes mmCIF and prints its path.

Full tutorial

The step-by-step tutorial covers installation, unit cells, bulk crystals, exact-count and dimension-based slabs, alternative faces, 36-chain fibrils, GLYCAM generation, GROMACS preprocessing and minimization, large systems, visualization, chain numbering, and troubleshooting.

Workflow-manager and LLM-agent orchestration

CelluloseForge does not embed an LLM, and an LLM is never required. Its deterministic CLI, JSON diagnostics, and JSON build reports allow an external workflow manager or software agent to use exactly the same documented commands as a human. Check dependency availability in machine-readable form first:

cellulose-forge doctor --json

For example, an external agent can translate this request:

Build a validated cellulose I-beta (110) slab with 4 layers, 20 chains per layer, DP 12, finite chains, 30 angstrom vacuum, and GLYCAM output.

into the following independently reproducible action:

cellulose-forge build \
  --allomorph I-beta \
  --shape slab \
  --face 1 1 0 \
  --layers 4 \
  --chains-per-layer 20 \
  --degree-polymerization 12 \
  --chain-boundary finite \
  --vacuum 30 \
  --padding-longitudinal 20 \
  --force-field glycam \
  --output ibeta_110_slab

The generated build_report.json records the interpreted scientific choices and realized system, including a residue-level C1 chirality check confirming D-cellulose geometry. Consumers should inspect that report and run the normal validation workflow instead of trusting an agent's textual account. A retained proof-of-concept record is available in validation/agent_orchestration_demo/.

Development and testing

uv sync --extra dev
uv run pytest --cov=cellulose_forge --cov-report=term-missing
uv run ruff check .
uv run mypy src

Continuous integration tests Python 3.11 and 3.13 on Linux and macOS, runs the GROMACS, OpenMM, and LAMMPS workflows, and runs the OpenFF tests and reduced OpenFF validators in their own environment.

License

CelluloseForge is distributed under the GNU General Public License, version 3 or later. See LICENSE or Licence.txt.

Metadata

Release files for cellulose-forge 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cellulose-forge 1.2.0
File Size Uploaded Provenance Actions
cellulose_forge-1.2.0.tar.gz 162.8 kB With provenance Details for cellulose_forge-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cellulose-forge 1.2.0
File Interpreter ABI Platform Actions
cellulose_forge-1.2.0-py3-none-any.whl Python 3 none any Details for cellulose_forge-1.2.0-py3-none-any.whl

Total release size: 321.0 kB

Release files / cellulose_forge-1.2.0.tar.gz

Download URL cellulose_forge-1.2.0.tar.gz
Size 162.8 kB
Tags Source
SHA-256 checksum
How to use checksums
d4f57e823d0b1f64c81a6aa66859219434e3093101ce4f2e999c094f0db39bec
BLAKE2b-256 checksum
How to use checksums
44f8bfefc2b4bf1183346bb25dca05e2e784ded7073bdcca363eeedb2fb62f9d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / cellulose_forge-1.2.0-py3-none-any.whl

Download URL cellulose_forge-1.2.0-py3-none-any.whl
Size 158.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d054c2027a60037c0c1bd0e3587c489a30c67849d994497c00b1e665b1555afe
BLAKE2b-256 checksum
How to use checksums
f357c9a757355f5ba588652e17aa7a99979c596de0e5348f8f400c7d03cdce80
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for cellulose-forge 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cellulose_forge-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page