Running the Examples

ChemFAST provides a suite of practical examples and tutorials to help users model various chemical systems. All examples follow the same underlying execution logic.

1. Acquiring the Examples

To keep the main repository lightweight, the examples are divided into two categories based on their file sizes:

1. Basic Examples (Included in the Repository) These are located directly in the examples/ directory of the cloned repository. They are lightweight and serve as the best starting point:

  • pi/: Linear Polyimide melt.

  • custom_forcefield_gaff/: Demonstrates how to use a custom GAFF database.

  • examples_others.zip: A collection of smaller examples (e.g., SPEs network, SPEs brushes, cis/trans rubber, lipid, core-shell-shaped RNA assembles) that are included in the main repository but can be extracted.

2. Advanced Examples (Download from Releases) Large-scale simulations with complex architectures are packaged separately. You can download these examples from the DoMD GitHub Releases page :

  • spes_brush/: Solid Polymer Electrolyte (SPE) brushes.

  • spes_network/: Cross-linked SPE networks.

  • aunps/: Gold nanoparticles and lipid bilayers complex.

  • core_shell_nps/: Core-shell nanoparticle structures with experiment DNA/RNA PDB structure.

The detailed introductions can be found in TUTORIALS section.

2. Execution Logic (Polyimide system as Example)

All examples share a standardized file structure and execution logic. We will use the Polyimide (pi) example to demonstrate.

Navigate to the example directory:

$ cd <path-to-DoMD>/examples/pi

Within any example directory, the scripts are organized into two operational modes:

  1. The “All-in-One” Script: Named after the system (e.g., polyimides.py). It executes the complete workflow (Backmapping -> Force Field -> Output).

    Note: In this mode, the initial Coarse-Grained (CG) generation and pre-equilibration have already been completed and saved in the CG_pre_eq/ folder to save your time.

  2. The “Step-by-Step” Scripts: Individual modules (cg.py, fg.py, ff.py, output.py) that allow you to run and inspect each stage independently. Intermediate data is serialized and passed between these steps using meta_*.pkl files.

2.1 End-to-End Workflow

Run the main script to process the pre-equilibrated CG configuration directly into an All-Atom model:

$ python polyimides.py

Outputs Generated:

  • chemfast.gro: The back-mapped All-Atom (AA) conformation.

  • chemfast.top: The GROMACS-compatible force field and topology file.

  • out_chemfast.xml: The PyGAMD xml input.

Purpose: These files are ready for immediate use in atomistic simulations using GROMACS or PyGAMD.

2.2 Step-by-Step Mode

To facilitate a deeper understanding of the ChemFAST internal logic or to customize specific stages, users may execute the individual S-CGFG functions sequentially.

  • Step 1: CG Topology Generation

    $ python cg.py

    Generates an initial CG configuration (e.g., linear chains) and force field parameters based on HSP (Hansen Solubility Parameters) predictions. This is typically used to prepare for pre-equilibration or reaction runs. (Note: This step is optional in this tutorial as a pre-equilibrated configuration is already provided).

    • Outputs: out_chemfast_cg.xml file for PyGAMD, and cg_params.txt as CG forcefield parameters.

  • Step 1.1: CG Parameterization (Standalone)

    $ python cg_params.py

    Generates CG simulation force field parameters only from specific monomers and reaction templates, without building the simulation box.

    • Output: cg_parameters.txt

  • Step 2: Back-mapping (CG to FG)

    $ python fg.py

    Tests the Coarse-Grained to Fine-Grained (AA) conversion. It reads the pre-equilibrated CG XML and embeds the all-atom monomers.

    • Outputs: AA conformations (PDB files stored in the aa_confs/ folder while argument write_molecule=True) and topology metadata (serialized as meta_aa_top.pkl).

  • Step 3: Force Field Parameterization

    $ python ff.py

    Performs all-atom force field parameterization by reading the meta_aa_top.pkl generated in the previous step.

    • Output: Assigned parameters (serialized as meta_ffs.pkl).

  • Step 4: Final Assembly

    $ python output.py

    Reads all the intermediate .pkl files and assembles the AA conformations and force field data into standard MD input formats.

    • Outputs: Final chemfast.gro, chemfast.top and out_chemfast.xml files.