Example Usage: SPECI-AUTOCOPASI Integration
===========================================

This guide illustrates how to use the SPECI workflow to prepare kinetic modeling inputs for AUTOCOPASI, automate CSV generation, and run time-course simulations in COPASI. This workflow is suitable for complex species such as CIPs, SSIPs, and IIPs.

Automated Input Preparation from SPECI
--------------------------------------

**1. Automated Extraction of Energies and Composition**

- **Input Preparation is Fully Automated:**  
  The required `.csv` files for AUTOCOPASI are automatically generated by the main SPECI script.  
  Simply provide a folder containing all `.log` files (output from quantum chemical calculations) for your species of interest.

- **How to Specify Input Folders:**
  In the main SPECI script, set the `directory_path` to point to the folder containing your log files:

  .. code-block:: python

      directory_path = "/Users/yourname/path/to/PM7-Gibbs/"   # Location of log files

- **Filename Cleaning:**  
  The script automatically processes log filenames to extract numerical indexes, ensuring clean, concise labels for each species.  
  For IIP calculations, additional cleaning (e.g., removing "lowest10_c2_a1_" or other prefixes) is available as code comments.

  Example snippet:

  .. code-block:: python

      name = filename.replace("speciationDFT", "")
      # For IIP-specific naming:
      name = name.replace("speciation", "")
      # Add or modify replace statements as needed

- **CSV Output Locations:**  
  Set where you want the main results to be saved:

  .. code-block:: python

      out_csv = "/Users/yourname/path/to/Energies.csv"                # Energies summary CSV
      csv_path = "/Users/yourname/path/to/elemental_composition.csv"  # Composition CSV

  Make sure to provide the full path for each output.

- **How the CSVs are Used:**  
  The main output files (`Energies.csv`, `elemental_composition.csv`) will be used as input for COPASI modeling.

  **Note:**  
  The filtered elemental composition CSV should also include any energies computed for *neutral donor ligands* that could dissociate—this is important for modeling ligand exchange equilibria.

**2. Flexibility of Workflow Blocks**

- Each preparation block (energy extraction, composition mapping, etc.) is modular:  
  You can run these blocks **at any time** and in any order, independent of previous runs or information.
- This makes the workflow robust and easily adaptable for different case studies or new species.

Running the SPECI-AUTOCOPASI Workflow
-------------------------------------

After the SPECI CSVs are generated, specify them for COPASI script input:

.. code-block:: python

    energy_csv = "/Users/yourname/path/to/Energies.csv"
    composition_csv = "/Users/yourname/path/to/elemental_composition.csv"
    output_path = "/Users/yourname/path/to/elementary_reactions.csv"   # Final input for AUTOCOPASI

The file `elementary_reactions.csv` is the **direct input for the AUTOCOPASI script** that will simulate time-dependent concentration profiles.

COPASI Script Execution & Output
--------------------------------

- **Running the Script:**  
  From your terminal or Python environment, execute the AUTOCOPASI script with the correct CSVs specified.

- **What is Output:**  
  - The script generates a COPASI-compatible file with all elementary reactions, kinetic parameters, and initial concentrations.
  - You will receive simulation outputs such as:
    - Time vs. concentration plots for all species
    - Raw simulation data in `.csv` or `.xml` format (COPASI native)
    - Optionally, visualizations or diagnostic files depending on your setup

- **Notes & Best Practices:**
  - Always check that your input CSVs have been generated and cleaned as intended (no duplicate or missing species labels).
  - Make sure to include any relevant neutral donor ligands in your composition file.
  - For expanded studies, simply add new log files to your input folder and rerun the corresponding block.

Troubleshooting
---------------

- If you encounter errors, verify all file paths, and make sure there are no formatting issues in your CSVs.
- Refer to comments in the SPECI and AUTOCOPASI scripts for further customization or to add new naming conventions.

References & Links
------------------

- See [AUTOCOPASI Installation](AUTOCOPASI_installation.html) for setup instructions.
- Review the main [SPECI Documentation](index.html) for background and input file formats.
- For more on kinetic modeling and COPASI, visit the [COPASI Project site](https://copasi.org/).