=============================
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.

**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 <https://github.com/DoMD-toolkit/DoMD/releases>`_ :

* ``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:

.. code-block:: bash

   $ 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:

.. code-block:: bash

   $ 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**

  .. code-block:: bash

     $ 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)**

  .. code-block:: bash

     $ 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)**

  .. code-block:: bash

     $ 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**

  .. code-block:: bash

     $ 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**

  .. code-block:: bash

     $ 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.