Single Molecule Generation

The primary API for generating a single biochar molecule is generate_biochar() (convenience function) or the lower-level BiocharGenerator class.

Generation pipeline

target_num_carbons
      │
      ▼
Carbon skeleton (PAH library seed + ring-growth)
      │  Parity-aware hex-lattice builder; 100 % aromatic for any size
      ▼
Oxygen assignment (functional groups dict or O/C-ratio-driven)
      │
      ▼
Hydrogen assignment (fill valences → target H/C ratio)
      │
      ▼
3D geometry
      │  ≤ 80 heavy atoms: ETKDGv3 embedding + MMFF94 minimisation
      │  > 80 heavy atoms: 2-D flat sheet + force-field minimisation
      ▼
OPLS-AA atom typing & partial charges
      │
      ▼
Validation (composition, geometry, steric clashes)
      │
      ▼
GROMACS export (.gro / .top / .itp)

Controlling size

The target_num_carbons parameter controls skeleton size. The generator uses the built-in PAH library for sizes up to 40 C, then grows the skeleton by appending fused hexagonal rings.

from biochar import generate_biochar

# Small molecule — exact match from PAH library
mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=24,   # coronene
    output_directory="output",
)

# Large sheet — hex-lattice growth path
mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=150,
    output_directory="output",
)

PAH library (seed molecules)

Molecule	C	Type
benzene	6	Classic
naphthalene	10	Classic
anthracene / phenanthrene	14	Linear / angular
pyrene	16	Pericondensed
chrysene / tetracene	18	Various
coronene	24	7-ring compact
hex_lattice_28/30/38/40	28–40	Graphene flakes

Controlling composition

H/C and O/C ratios are set as targets with configurable tolerances:

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=80,
    H_C_ratio=0.65,       # high H → lower pyrolysis temperature
    H_C_tolerance=0.10,   # accept ± 10 %
    O_C_ratio=0.20,       # high O → more functional groups
    O_C_tolerance=0.10,
)

Typical values by pyrolysis temperature:

Temperature	H/C	O/C
300–400 °C	0.6–0.8	0.15–0.25
500–600 °C	0.4–0.6	0.08–0.15
700–800 °C	0.2–0.4	0.02–0.08

Pentagon ring defects

Real biochar contains both 6-membered (hexagonal) and 5-membered (pentagonal) rings due to incomplete graphitization. The defect_fraction parameter controls the probability that each ring added during skeleton growth is a pentagon instead of a hexagon.

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,
)

Guidance on defect_fraction values:

Value	Effect
0.0 (default)	Pure hexagonal PAH — flat graphene-like sheet
0.05–0.10	Mild disorder — a few curvature-inducing defects
0.10–0.20	Realistic amorphous biochar topology
> 0.30	Highly disordered — may need more retries to kekulize

Pentagon rings introduce curvature and parity constraints. The generator automatically handles parity (even/odd node count) to ensure each structure can be kekulized, retrying with a different sub-seed up to 5 times if needed.

Reproducibility

Pass an integer seed to get deterministic output:

mol, coords, gro, top, itp = generate_biochar(
    target_num_carbons=80,
    seed=42,
)

Using the class API

For more control, use BiocharGenerator directly:

from biochar import BiocharGenerator, GeneratorConfig

config = GeneratorConfig(
    target_num_carbons=100,
    H_C_ratio=0.4,
    O_C_ratio=0.08,
    functional_groups={"phenolic": 4, "carboxyl": 1},
    seed=99,
)
gen = BiocharGenerator(config)
mol, coords, composition = gen.generate()
gen.print_summary()
gro, top, itp = gen.export_gromacs("output", "bc_custom")