Sovereign 8s.is mirror of standardgalactic/kinetic_model
  • Jupyter Notebook 96.3%
  • Python 3.2%
  • Shell 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Aleksandr Avdoshin 48abd836fe
Revise README for kinetic model project
Updated README to reflect changes in project structure and content.
2025-12-20 18:26:06 +01:00
.git_backup recover after crush 2025-12-12 11:53:11 +01:00
build/lib/kinetic_model added diffusion ml prediction 2025-05-16 11:43:19 +02:00
data refresh readme 2025-12-15 14:10:04 +01:00
examples refresh readme 2025-12-15 14:10:04 +01:00
notebooks recover after crush 2025-12-12 11:53:11 +01:00
src fixed readme 2025-12-18 11:44:46 +01:00
tests Extended ads prediction for CnH2n > 10 2025-05-21 14:15:46 +02:00
.gitignore git ignore 2025-12-15 14:08:53 +01:00
clean_requirements.txt new examples 2025-07-16 10:37:59 +02:00
environment.yml initial project import 2025-05-06 14:45:13 +02:00
LICENSE Add MIT License 2025-12-19 12:02:57 +01:00
pyproject.toml initial project import 2025-05-06 14:45:13 +02:00
README.md Revise README for kinetic model project 2025-12-20 18:26:06 +01:00
requirements-clean.txt fix diffusion 2025-09-11 14:47:03 +02:00
requirements.txt Nams code is implemented to the project only not to reactor sim 2025-06-20 13:50:03 +02:00

Kinetic Model

Multiscale toolkit for simulating Ni-catalysed olefin chain growth, diffusion, and adsorption.

Overview

  • Deterministic ODE reactor solver (kinetic_model.core) that handles coupled reaction networks and capacity-weighted diffusion between compartments.
  • Machine-learning surrogates for adsorption capacities and intracrystalline diffusion (KNN/Gaussian-process regressors stored under data/processed).
  • Thermochemistry and energy-profile tooling (kinetic_model.energy_profile) to turn DFT results into relative free-energy landscapes and barrier dictionaries that plug directly into the reactor simulations.
  • Supplementary notebooks (notebooks/) for training surrogates and analysing experimental/DFT data, plus reproducible examples in examples/.

Repository Layout

Path Purpose
src/kinetic_model/core Base Reaction ODE solver, diffusion-aware reactor (Reaction_Diffusion), and Eyring rate helper.
src/kinetic_model/constants ML models and utilities for adsorption/diffusion, energy-barrier loaders, and thermodynamic constants.
src/kinetic_model/energy_profile Parsers for DFT folders, thermochemistry (harmonic, anharmonic, and free-rotor treatments), relative energy calculators, and plotting helpers.
src/kinetic_model/simulation High-level simulation drivers (ReactorSimulation, chemisorption variants), reaction-list builders, plotting utilities, and synthetic-data generators.
data/ Raw DFT structures, gas-phase molecules, YAML metadata, and pretrained .pkl surrogates (data/processed).
examples/ Ready-to-run settings files and notebooks demonstrating energy-profile extraction.
notebooks/ Jupyter notebooks for adsorption/diffusion model development and loading studies.
tests/ Pytest suite that covers kinetic core logic, diffusion handling, rate calculations, and runner utilities.

Installation

  1. Create an environment (optional but recommended):
    conda env create -f environment.yml
    conda activate kinetic_model
    
    or manually install Python ≥3.12.
  2. Install the package and dependencies:
    pip install -r requirements.txt
    pip install -e .
    
    The editable install exposes kinetic_model for notebooks, scripts, and tests.

Quick Start

from kinetic_model.simulation.run_reactor import ReactorSimulationChemisorptionSimplified
from kinetic_model.constants.energy_profile import EnergyBarriersSimplifyed

energy = EnergyBarriersSimplifyed(pressure=5.0, temperature=320.0)
sim = ReactorSimulationChemisorptionSimplified(
    N=16,
    T=320.0,
    pressure=5.0,
    L=8.0,
    time_hours=2.0,
    n_steps=500,
    diff_model_path='../data/processed/diffusion_extrap_place_holder_model.pkl',
    ads_model_path='../data/processed/knn_adsorption_slope_model.pkl',
    energy_model=energy,
    initial_concs={'CatC2(C2)': 1e-2, 'C2': 1}
)
distribution_df, probability_traces = sim.run()
  • distribution_df summarises the final olefin chain-length distribution and probabilities.
  • probability_traces (time-series DataFrame) tracks intra-/extra-crystalline concentrations for each chain length.

Energy Profiles and Barriers

  1. Prepare DFT folders: populate data/structures/<model_method>/<pathway>/<system> and data/gas-phase-molecules/<model>/… with POSCAR/mol.xyz, energy.dat, freq.txt, and optional rotAtoms.yaml.
  2. Compute thermochemistry:
    
     from kinetic_model.energy_profile.energy_processing import calculate_relative_energies
     import os 
     import numpy as np
    
     temperatures = [300]        # Can be varied
     pressures = [101325.]           # Can be carried
     models = ['QM-QM_TPSSh-PBED3']   # Options: ['QM-QM_M06L-PBED3', 'QM-QM_TPPSh-PBED3]  
     pathways = ['trigonal']         # Options: ['trigonal', 'hexagonal']
     ref_struc = '1'                 # Choose either 1 or 5
     energy_type = 'Gibbs free energy'   # Options: ['Electronic energy', 'Enthalpy', 'Gibbs free energy']
     energy_unit = 'kJ/mol'              # Options: ['eV', 'kJ/mol', 'kcal/mol']
    
     custom_order = ["1", "2", "3", "4", "5", "5a", "6", "1p", "7", "8", "9", "5p", "6p", "1pp", "10", "11", "12", "5pp", "6pp", "1ppp", "2-3", "3-4", "6-1p", "7-8", "8-9", "6p-1pp", "10-11", "11-12", "6pp-1ppp"]  # Use for sorting the intermediates in a table (or pd.DataFrame)
    
     rel_results = calculate_relative_energies(
         structures_dir=os.path.abspath('../data/structures'),
         molecules_dir=os.path.abspath('../data/gas-phase-molecules'),
         temperatures=temperatures,
         models=models,
         ref_struc=ref_struc,
         pathways=pathways,
         pressures=pressures
     )
    
    
  3. Convert to barriers: instantiate EnergyBarriers or EnergyBarriersSimplifyed with the target temperature/pressure; call get_energy_barriers() to obtain ΔG‡ dictionaries that feed prepare_constants_* or a custom simulation setup.

Surrogate Models & Data

  • Adsorption: data/processed/knn_adsorption_model.pkl contains the grouped/scaled KNN (AdsorptionKNN / AdsorptionKNNSlopeExtrap). Re-train using notebooks/adsorbtion_process_ml.ipynb, then joblib.dump the estimator.
  • Diffusion: data/processed/diffusion_model*.pkl stores LightGBM-based regressors (see notebooks/diffusion_process_ml.ipynb). Rates are later converted to s⁻¹ via pore-geometry scaling inside ReactorSimulation.
  • DFT sources: data/structures, data/gas-phase-molecules, and data/formulae.yaml describe the thermochemistry inputs. The mini data/README highlights shared intermediates between pathways.

Examples & Notebooks

  • test_soft.ipynb - the main example file where you can find more detailed examples how to use current soft. examples/settings.yaml and examples/c8_energy_profiles_settings.yaml demonstrate how to configure pathway, model, and plotting options for energy-profile reports.
  • Notebooks in notebooks/ reproduce adsorption/diffusion training, sanity-check Eyring prefactors, and explore C₂ loading. They assume you installed the package in editable mode so imports resolve.

Testing & Development

  • Run the full suite with pytest from the repository root. Key tests (tests/test_core.py, tests/test_diffusion_behavior.py, etc.) validate ODE integration, diffusion bookkeeping, barrier-to-rate conversions, and runner wiring.
  • When adding features, prefer dropping new modules under src/kinetic_model and extend the pytest coverage alongside; notebooks and examples can reference the same public API.

License

The project is released under the MIT License


Questions or ideas? Open an issue or start a discussion in your preferred tracker—contributions that improve the kinetic workflow, data parsers, or surrogate accuracy are very welcome.