gromacs_export

class biochar.gromacs_export.GromacsExporter(output_directory='.')

Bases: object

High-level interface for exporting to GROMACS files.

Parameters:

output_directory (str)

export(mol, coords, atom_types, charges, molecule_name='BC', basename='structure', include_periodic_box=False, box_size=None)

Export molecule to GROMACS files.

Parameters:

• mol – RDKit molecule

• coords – 3D coordinates

• atom_types – Atom type mapping

• charges – Charge mapping

• molecule_name – Molecule name

• basename – Base filename (without extension)

• include_periodic_box – If True, create periodic box

• box_size – Box dimensions [Lx, Ly, Lz]

Return type:

Tuple[Path, Path, Path]

Returns:

(gro_path, top_path, itp_path)

Parameters:

• mol (Mol)

• coords (ndarray)

• atom_types (Dict[int, str])

• charges (Dict[int, float])

• molecule_name (str)

• basename (str)

• include_periodic_box (bool)

• box_size (ndarray | None)

class biochar.gromacs_export.GROFileWriter

Bases: object

Write GROMACS structure (.gro) files.

static write(filepath, mol, coords, molecule_name='BC', box_vectors=None, title=None)

Write .gro structure file.

Parameters:

• filepath – Output file path

• mol – RDKit molecule

• coords – 3D coordinates (in Ångströms, will be converted to nanometers)

• molecule_name – Name of molecule in GRO file (max 5 chars for .gro format)

• box_vectors – Box vectors (3x3 matrix) for periodic systems (in nm)

• title – Optional title line

Parameters:

• filepath (str)

• mol (Mol)

• coords (ndarray)

• molecule_name (str)

• box_vectors (ndarray | None)

• title (str | None)

Note

Residue names in GROMACS .gro format are limited to 5 characters. Suggested naming conventions for mixed biochar simulations: - Temperature-based: BC400, BC600, BC800 - Composition: BCH05 (H/C=0.5), BCO10 (O/C=0.10) - Sequential: BC001, BC002, BC003

Coordinate Units: - Input: RDKit coordinates (Ångströms, Å) - Output: GROMACS coordinates (nanometers, nm) - Conversion: 1 Å = 0.1 nm

class biochar.gromacs_export.TOPFileWriter

Bases: object

Write GROMACS topology (.top) files.

static write(filepath, mol, atom_types, charges, molecule_name='BIOCHAR', forcefield_path='oplsaa.ff/forcefield.itp', include_dihedrals=True)

Write .top topology file.

Parameters:

• filepath – Output file path

• mol – RDKit molecule

• atom_types – Dictionary of {atom_idx: opls_type}

• charges – Dictionary of {atom_idx: charge}

• molecule_name – Name of molecule/residue

• forcefield_path – Path to forcefield file (relative or absolute)

• include_dihedrals – If True, include dihedral section

Parameters:

• filepath (str)

• mol (Mol)

• atom_types (Dict[int, str])

• charges (Dict[int, float])

• molecule_name (str)

• forcefield_path (str)

• include_dihedrals (bool)

class biochar.gromacs_export.ITPFileWriter

Bases: object

Write GROMACS include topology (.itp) files.

Note: .itp files are typically included in a .top file that defines atom types. We don’t include [ atomtypes ] here to avoid duplication.

static write(filepath, mol, atom_types, charges, molecule_name='BIOCHAR', include_dihedrals=True)

Write .itp molecule definition file.

Parameters:

• filepath – Output file path

• mol – RDKit molecule

• atom_types – Dictionary of {atom_idx: opls_type}

• charges – Dictionary of {atom_idx: charge}

• molecule_name – Name of molecule

• include_dihedrals – If True, include dihedral section

Parameters:

• filepath (str)

• mol (Mol)

• atom_types (Dict[int, str])

• charges (Dict[int, float])

• molecule_name (str)

• include_dihedrals (bool)

Note

The .itp file includes atom type definitions for standalone use. When included in a .top file, the atom types will be shared.

class biochar.gromacs_export.MultiSheetGROWriter

Bases: object

Write a multi-residue .gro file for surface systems.

Each sheet occupies a separate residue with an incrementing residue number. Atom numbering is global and contiguous across all sheets.

static write(filepath, sheets, box_vectors, title=None)

Write a single .gro containing atoms from multiple sheets.

Parameters:

• filepath – Output path.

• sheets – List of SheetResult objects. Each must expose .mol (RDKit Mol), .coords (Å, shape N×3), and .molecule_name (str ≤ 5 chars).

• box_vectors – Periodic box vectors in nm (orthogonal 1-D or full 3×3 triclinic).

• title – Optional title line.

Parameters:

• filepath (str)

• sheets (list)

• box_vectors (ndarray)

• title (str | None)

class biochar.gromacs_export.SurfaceTopologyWriter

Bases: object

Write .top files for multi-sheet surface systems.

static write(filepath, sheets, itp_paths, sheets_identical, system_name='Slit Pore Surface', forcefield_path='oplsaa.ff/forcefield.itp')

Write a combined .top for a surface system.

When sheets_identical is True:

• One #include for the single .itp.

• [ molecules ] lists the molecule name once with count = N.

When sheets_identical is False:

• One #include per distinct .itp.

• [ molecules ] lists each molecule name once with count = 1.

Parameters:

• filepath (str)

• sheets (list)

• itp_paths (list)

• sheets_identical (bool)

• system_name (str)

• forcefield_path (str)