Quick Start

From pyrolysis temperature and feedstock

Drive composition (H/C, O/C, aromaticity) directly from pyrolysis conditions using the UC Davis Biochar Database model:

from biochar import generate_biochar

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=80,
    temperature=600,          # °C
    feedstock="softwood",     # optional; omit for pooled-feedstock curve
    output_directory="output",
    basename="bc600_sw",
    molecule_name="BC600",
    seed=42,
)

Explicit H_C_ratio / O_C_ratio / aromaticity_percent kwargs override the model-derived values when provided.

Query reference properties (surface area, pH, CEC, …) for any temperature:

from biochar import properties

props = properties(600, feedstock="softwood")
print(props["H_C_ratio"], props["surface_area_m2_g"])

From the command line:

biochar-gen --temperature 600 --feedstock softwood --carbons 80 --name BC600 --seed 42

Single molecule

Generate a biochar molecule and write GROMACS files in one call:

from biochar import generate_biochar

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=80,
    H_C_ratio=0.5,
    O_C_ratio=0.10,
    output_directory="output",
    basename="bc400",
    molecule_name="BC400",
    seed=42,
)

This produces output/bc400.gro, output/bc400.top, and output/bc400.itp.

With functional groups

Specify exact functional group counts instead of relying on the O/C ratio:

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=60,
    functional_groups={"phenolic": 3, "carboxyl": 1, "ether": 2},
    output_directory="output",
    basename="bc_fg",
    seed=42,
)

With pentagon defects

Add topological disorder by inserting 5-membered rings during skeleton growth:

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=80,
    H_C_ratio=0.4,
    O_C_ratio=0.05,
    defect_fraction=0.15,   # ~15 % of rings will be pentagons
    output_directory="output",
    seed=42,
)

Slit-pore surface

Stack two parallel sheets separated by a 10 Å pore:

from biochar import generate_surface

sheets, gro, top, itps = generate_surface(
    target_num_carbons=50,
    functional_groups={"phenolic": 2},
    pore_diameter=10.0,
    num_sheets=2,
    output_directory="output",
    basename="slit_pore",
    seed=42,
)

Run in GROMACS

gmx grompp -f em.mdp -c output/bc400.gro -p output/bc400.top -o em.tpr
gmx mdrun -v -deffnm em

See GROMACS Workflow for a complete energy-minimisation and MD workflow.