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:

    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:

    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:

    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:

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.