okin 0.1.4

Organic-Kinetics (okin) is a collection of chemistry-related Python tools

OKIN

Organic Kinetics is a package to perform tasks useful for understanding kinetic behaviour in organic chemistry.
Requires python >= 3.9 unless CMake is available then python >=3.8.

Installation

From PyPI:

Base package

• Create and activate a dedicated environment
• pip install re_add_modeler

With Modeling

• make sure COPASI is installed (https://copasi.org/Download/)
• download and unzip 'python implementation of COPASI': https://drive.google.com/file/d/1cVNLU4SBsz0JhC48MO69wVSLH-RpyIt6/view?usp=sharing
• OR clone github repo of 'python implementation of COPASI' https://gitlab.com/heingroup/py_copasi
• The modeling class requires the path to that folder as an argument modler = Modler(copasi_path=local_copasi_path)

Usage

1. ChemDraw Parser

Parse reactions/mechanistic cycles directly from ChemDraw .cdxml files, allowing you to extract and work with reaction information.

Example:

from okin.cd_parser.cd_parser import CDParser

# Load a ChemDraw file
cd_parser = CDParser(file_path="base_cycle.cdxml", draw=True)

# Extract all reactions
reactions = cd_parser.find_reactions()
print(f"Reactions found in {cd_parser.file_path}:")
for rct in reactions:
    print(rct)

• file_path: Path to your ChemDraw .cdxml file.
• draw=True: Optionally renders the Chemdraw File with the bounding boxes. These determine which parts to treat as one reaction or a new one.
• find_reactions(): Returns a list of reaction objects parsed from the file, which can be used for other functions of this package (simulation, VTNA, or modeling).

2. Rate Equations

Calculate the Steady-State rate equation for a given mechanism.

Example:

from okin.simulation.rate_equation import RateEquation

# Define reactions (reversible or irreversible)
reactions = ["A + cat <==> cat1", "cat1 + B -> cat + P", "B + cat -> cat_I"]
rate_eq = RateEquation(reactions)

# Display LaTeX rate law
print(rate_eq.debug_string)
rate_eq.show_latex_rate_law()

• The used catalytic species need to be named cat for base catalyst and cat<nr> e.g. cat1 for all intermediates. Deactivated cat needs to be named catI.
• Reversible reactions should use <==>; irreversible reactions use ->.
• show_latex_rate_law() renders the final rate law in LaTeX format. If latex is not available it prints the LaTeX string.
• rate_eq.debug_string shows the math that has been performed

3. Simulation

Okin allows you to simulate chemical reaction kinetics over time with specified rate constants and initial concentrations.

Fixed Simulation

from okin.simulation.simulator import Simulator
import matplotlib.pyplot as plt
from okin.base.chem_plot_utils import apply_acs_layout

# Define mechanism, rate constants, and initial concentrations
mechanism = ["A + cat -> cat1", "cat1 + B -> cat + P", "X + cat -> cat_deact"]
k_dict = {"k1": 10, "kN1": 5, "k2": 3, "kN2": 0, "k3": 0.005, "kN3": 0}
c_dict = {"A": 1.0, "B": 1.2, "cat": 0.05, "P": 0.0, "X": 0.1}

# Setup and run simulation
sim = Simulator()
sim.setup(mechanism, k_dict, c_dict)
sim.simulate(start=0, stop=80, nr_time_points=40)

# Access results
df = sim.result

# Plot results
plt.scatter(df["time"], df["A"])
plt.scatter(df["time"], df["B"])
plt.scatter(df["time"], df["P"])
plt.xlabel("time")
plt.ylabel("concentration")
apply_acs_layout()
plt.show()

• setup() takes mechanism as strings, rate constants (k_dict), and initial concentrations (c_dict).
• simulate() runs the time evolution over a specified range with a given number of points.
• Results are stored in sim.result as a DataFrame for plotting or further analysis.
• Reversibility is determined by k-values and not by arrows.

Interactive Simulation

from okin.simulation.tc_engine import InteractiveTimeCourse

mechanism = [
    "A + cat = cat1",
    "cat1 + B = P + cat",
    "cat1 + A  = catI"
]
initial_conditions = {
    "A": 1.0, 
    "B": 1.2,
    "cat": 0.01
}
conserved_species = {
    # Specify any conservation equations
    # Example:
    # 'E_free': 'E_total - ES'
}
k_init = {
    "k1": 1,
    "k2": 0,
    "k3": 1,
    "k4": 0,
    "k5": 100,
    "k6": 10
}

portrait = InteractiveTimeCourse(
    mechanism, initial_conditions, conserved_species, k_init, mode="vtna")
portrait.run()

• mechanism contains the elementary steps as strings
• Reversible arrow: =: is highly recommended. Non-reversible arrow ->: use with care
• initial_conditions are the starting concentrations. Species not mentioned here are set to 0.
• k_dict contains the starting k-values. Range from 0-100 in steps of 0.1
• k1 (forward for rct1); k2 (backwards for rct1); !different from fixed simulation which has k1 and kN1!
• allowed_modes = ["vtna", "tc", "phase"].
• "vtna" shows time course, catalyst concentration and VTNA for doubled [cat]. Slower response time than other modes.
• "tc" shows only the time course. Good for fast exploration.
• "phase" shows customizable phase diagrams

4. VTNA (Variable Time Normalization Analysis)

Determine reaction orders via VTNA (https://pubs.rsc.org/en/content/articlelanding/2019/sc/c8sc04698k).

Example:

from okin.kinetics.vtna import ClassicVTNA

# Assuming df1 and df2 are results from two simulations or experiments
vtna = ClassicVTNA(df_rct1=df1, df_rct2=df2, species_col_name="cat", product_col_name="P", time_col_name="time")

# Best kinetic order for the species
print(f"Best order for cat: {vtna.best_order}")

# Plot normalized VTNA data
vtna.show_plot()

• df_rct1, df_rct2: DataFrames containing time-course data for two experiments that only vary in one concentration.
• species_col_name: Name of the species for which the initial concentration was changed. Same name as the provided data.
• product_col_name: Name of the column used to track reaction progress. Same name as the provided data.
• time_col_name: Name of the time column. Same name as the provided data.
• show_plot(): Visualizes the normalized reaction rates for comparison.

5. Modeling with COPASI

Okin integrates with COPASI (https://copasi.org/) to build and fit kinetic models from experimental data.

Example:

from okin.model.modler import Modler

# Initialize Modler with local COPASI path
modler = Modler(copasi_path=r"D:\python_code\hein_modules\local_copasi")

# Set reaction mechanism
reactions = ["A + cat -> cat1", "cat1 + B -> cat + P", "X + cat -> cat_I"]
modler.set_m_reactions(reactions)

# Add experimental CSV data
modler.add_experiment_csv(["data1.csv","data2.csv"])

# Specify species for model fitting
modler.set_species_for_model(["P","A"])
modler.set_species_to_match(["P","A","B"])

# Configure COPASI optimization settings
modler.set_copasi_settings({"number_of_generations":50,"population_size":50})

# Create and fit the model
modler.create_single_model()
modler.show_model_fit(save_modeled_data=True, show_all=True)

• copasi_path: Path to the local COPASI folder (LINK WILL BE ADDED SOON)
• reactions: List of reactions defining the mechanism.
• experiment CSV files: Paths to one or more CSV files with experimental data .
• species_for_model: Species used for internal error calculations.
• species_to_match: Species used by COPASI to fit the model.
• copasi_settings: Dictionary of COPASI optimization parameters
• create_single_model(): Runs COPASI.
• show_model_fit(): Displays the fitted model and optionally saves modeled data.

License

This project is licensed under the MIT License.

Future

This project will receive updates in the near future.