KARIKÓ-SCRIPTS I

# SCRIPTS-KARIKÓ I – Complete Documentation This archive contains a collection of Python scripts (`.py`), Bash scripts (`.sh`), JSON configuration files, and Markdown documentation used to set up, run, and analyze coarse‑grained (Martini) molecular dynamics simulations of lipid nanoparticles (LNPs) containing PEG or PGL. The scripts are part of the research project *“Molecular Basis of PEG Immunogenicity and the Biocompatibility of Polyglycerol”*. They were used to generate data for the corresponding manuscript and patent application. --- ## Table of Contents 1. [Main Pipelines and Optimisation](#1-main-pipelines-and-optimisation)2. [System Setup and Parameterisation](#2-system-setup-and-parameterisation)3. [Running Simulations](#3-running-simulations)4. [Analysis of Trajectories and Properties](#4-analysis-of-trajectories-and-properties)5. [Thermodynamic and Energy Data (Examples)](#5-thermodynamic-and-energy-data-examples)6. [Reports and Summaries](#6-reports-and-summaries)7. [Validation and Diagnostics](#7-validation-and-diagnostics)8. [Correction and Maintenance](#8-correction-and-maintenance)9. [Video and Figure Generation (Optional)](#9-video-and-figure-generation-optional)10. [Usage Notes](#usage-notes)11. [License](#license)12. [Citation](#citation) --- ## 1. Main Pipelines and Optimisation | File | Description ||------|-------------|| `advanced_kariko_optimization.json` | Example JSON with advanced optimisation parameters. || `advanced_kariko_pipeline.py` | Advanced pipeline integrating mRNA optimisation, LNP assembly, and simulation setup. || `complete_md_pipeline.py` | Orchestrates all steps of a molecular dynamics workflow (minimisation, equilibration, production). || `final_kariko_mrna_optimizer.py` | Final version of the mRNA sequence optimiser. || `gromacs_visualization.py` | Generates plots from GROMACS output files (`.xvg`). || `kariko_optimizer.py` | General optimiser combining mRNA and lipid parameters. || `platform_summary.py` | Summarises platform information (GROMACS version, hardware). || `precise_kariko_pipeline.py` | Main pipeline for preparing and running Karikó‑style LNP‑mRNA simulations. || `production_kariko_optimizer.py` | Optimises production parameters (steps, temperature, pressure) for LNP simulations. || `production_mrna_optimizer.py` | Optimises mRNA sequences for high‑yield production. || `vaccine_production_pipeline.py` | Complete pipeline for mRNA vaccine production, from sequence to LNP. | ## 2. System Setup and Parameterisation | File | Description ||------|-------------|| `assemble_kariko_lnp_mrna.py` | Assembles the Karikó‑style LNP‑mRNA complex. || `assemble_lnp_mrna_complex.py` | Alternative LNP‑mRNA assembly script. || `check_structure.py` | Checks structure integrity (missing atoms, broken bonds). || `create_martini_lnp.py` | Creates a lipid nanoparticle using the Martini coarse‑grained force field. || `create_proper_systems.py` | Generates systems with appropriate parameters (force field, solvent, ions). || `create_simple_systems.py` | Generates simplified systems for quick testing. || `create_working_system.py` | Creates a single working simulation system. || `create_working_systems.py` | Creates multiple working systems with correct topology. || `generate_kariko_mrna_structure.py` | Builds a 3D structure of mRNA from an optimised sequence. || `generate_mrna_structure.py` | Builds a generic mRNA structure. || `gromacs_diagnostic.py` | Analyses GROMACS logs for errors or warnings. || `parameterize_kariko_system.py` | Assigns atom types and charges for the Karikó system. || `parameterize_system.py` | Generic parameterisation for lipid systems. || `simulation_status_report.py` | Reports the status of running/completed simulations. | ## 3. Running Simulations | File | Description ||------|-------------|| `COMPLETE_PEG_PGL_COMPARISON.sh` | Triggers the systematic comparison between PEG and PGL. || `CREATE_WORKING_SIMULATIONS.sh` | Launches creation of working simulation systems. || `FINAL_SUCCESS_SIMULATIONS.sh` | Final batch of successful simulations. || `FINAL_WORKING_SOLUTION.sh` | Final working solution launcher. || `RUN_ALL_SIMULATIONS.sh` | Launches all simulations in a batch. || `RUN_COMPATIBLE_SYSTEMS.sh` | Runs systems that are topology‑compatible. || `RUN_DOMAIN_ANALYSIS.sh` | Runs domain‑specific analysis (hinge regions, etc.). || `RUN_FINAL_SIMULATIONS.sh` | Launches final simulations after all adjustments. || `RUN_PEG_PGL_COMPARISON.sh` | Main script for PEG vs PGL comparison. || `RUN_PFIZER_LNP.sh` | Runs simulations of the Pfizer‑like LNP (exact composition). || `RUN_PFIZER_PRODUCTION.sh` | Production runs for the Pfizer system. || `RUN_PRODUCTION.sh` | Basic production launcher. || `RUN_PRODUCTION_FIXED.sh` | Production launcher with fixes. || `RUN_PRODUCTION_SIMULATIONS.sh` | Main script to launch production MD simulations in batch. || `RUN_REAL_SIMULATIONS.sh` | Launches the actual (real) simulations. || `SIMPLE_WORKING_SIMULATION.sh` | Simple simulation launcher for testing. || `WORK_START.sh` | Environment initialisation script. || `WORK_START_FIXED.sh` | Fixed environment initialisation. || `final_corrected_simulation.sh` | Final simulation with all corrections applied. || `final_kariko_martini.sh` | Final version of the Martini simulation script. || `fixed_pfizer_simulation.sh` | Runs fixed Pfizer simulation. || `kariko_martini_simulation.sh` | Generic Martini simulation launcher. || `kariko_working_simulation.sh` | Working Karikó simulation launcher. || `run_gromacs_simulation.sh` | Generic GROMACS simulation wrapper. || `run_kariko_martini.sh` | Runs coarse‑grained Martini simulations of the Karikó system. || `run_kariko_nmrbox_proper.sh` | Runs simulations on the NMRbox platform with correct settings. || `run_kariko_nmrbox_simulation.sh` | Launcher for NMRbox. || `run_kariko_simulation_fixed.sh` | Fixed simulation launcher. || `run_kariko_with_working_gromacs.sh` | Uses a working GROMACS executable. || `run_peg_pgl_comparison.sh` | Internal script for PEG vs PGL comparison. || `run_without_omp.sh` | Runs simulation without OpenMP (single thread). || `use_working_system.sh` | Switches to a known working system configuration. | ## 4. Analysis of Trajectories and Properties | File | Description ||------|-------------|| `ANALYSIS_SUMMARY.md` | Summary of analyses performed. || `COMPARE_RESULTS.sh` | General results comparison script. || `FIXED_ANALYZE_PEG_PGL.py` | Corrected version of the PEG vs PGL analysis. || `analyze_existing_simulations.py` | Processes already‑finished simulations and extracts metrics. || `analyze_gromacs_results.sh` | Runs several GROMACS analysis tools (RMSD, gyration, H‑bonds, etc.). || `analyze_kariko_simulation.py` | Specific analysis for Karikó simulations. || `analyze_kariko_structure.py` | Structural analysis (H‑bonds, dihedrals). || `analyze_peg_pgl.py` | Compares PEG and PGL systems (flexibility, energy, contacts). || `analyze_pfizer_composition.sh` | Shell wrapper for Pfizer composition analysis. || `analyze_pfizer_systems.py` | Analysis of Pfizer‑like systems. || `analyze_simulations.py` | Generic analysis for multiple simulations. || `analyze_trajectory.py` | General trajectory analysis (RMSD, RMSF, radius of gyration, etc.). || `compare_domain_dynamics.sh` | Compares dynamics of different protein domains. || `compare_domain_states.sh` | Compares conformational states of domains. || `compare_peg_pgl_properties.sh` | Shell script to compare properties of PEG and PGL. || `plot_gyration.py` | Plots radius of gyration over time. || `plot_rmsd.py` | Plots RMSD over time. || `trajectory_analysis_report.json` | JSON report generated by trajectory analysis (example). | ## 5. Thermodynamic and Energy Data (Examples) | File | Description ||------|-------------|| `peg_coords.info` | Coordinates information for PEG system. || `peg_energy.xvg` | Example energy data for PEG. || `peg_rmsd.xvg` | Example RMSD data for PEG. || `peg_vs_pgl_comprehensive_report.json` | Comprehensive comparison report (scores, properties, recommendations). || `pgl_coords.info` | Coordinates information for PGL system. || `pgl_energy.xvg` | Example energy data for PGL. || `pgl_rmsd.xvg` | Example RMSD data for PGL. || `simulation_analysis_report.json` | Example JSON report of simulation analysis. || `simulation_status_detailed.json` | Detailed simulation status (example). | ## 6. Reports and Summaries | File | Description ||------|-------------|| `COMPLETE_NATURE_REPORT.md` | Full Nature‑style report (introduction, methods, results). || `FINAL_RESULTS_SUMMARY.md` | Summary of final results (tables, figures). || `INTERPRETATION_REPORT.md` | Interpretation of results and discussion. || `KARIKO_METHODOLOGY_SUMMARY.md` | Detailed description of the methodology. || `PEG_PGL_COMPARISON_WORKFLOW.md` | Workflow of the PEG vs PGL comparison. || `SIMULATION_SUMMARY.md` | Summary of all simulations performed. || `SUCCESS_REPORT.md` | Report of successful simulation runs. || `charge_explanation.md` (Portuguese) | Explanation of charge assignments. || `charge_explanation_en.md` | English version of charge explanation. || `gromacs_simulation_report.json` | Example report from GROMACS. || `script_list.txt` | Automatically generated list of all scripts (may be outdated). || `simulation_diagnostic.txt` | Diagnostic output example. | ## 7. Validation and Diagnostics | File | Description ||------|-------------|| `CHECK_VIDEO_PROGRESS.sh` | Checks progress of video generation. || `CLEAN_ANALYSIS_DIRS.sh` | Cleans up analysis directories. || `DIAGNOSE_TRAJECTORIES.sh` | Diagnoses trajectory issues (PBC, missing frames). || `DIAGNOSTIC_ENERGY.sh` | Energy diagnostic script. || `DELETE_WRONG_VIDEOS.sh` | Deletes incorrectly generated videos. || `ENHANCE_ALL_FRAMES.sh` | Enhances frames for better visualisation. || `ENHANCE_DOMAIN_RESOLUTION.sh` | Improves resolution of domain movies. || `ENHANCE_IGE_FRAMES.sh` | Enhances frames for IgE simulations. ||