MolAlign: CLI Batch Processing Manual

MolAlign is the command-line powerhouse of the suite. It is designed to stitch multiple reaction segments (e.g., separate IRC calculations) into one seamless, physically consistent trajectory.

1. Core Concept: The "Domino" Alignment Unlike simple concatenation, MolAlign uses a Chained Alignment strategy:

   1. Reference: The first file is established as the fixed reference frame.
   2. Mapping & Flip: For every subsequent file, it automatically detects if the atoms are ordered differently or if the trajectory needs to be reversed (End-to-Start matching).
   3. Transformation: It applies the optimal rotation and translation (Kabsch Algorithm) to align the new segment perfectly to the existing chain.
   4. Bridging: To ensure a smooth transition, MolAlign checks the junction between segments. If the RMSD exceeds a defined threshold, intermediate "bridging points" are interpolated to eliminate jumps.
   5. Energy Stitching: It calculates energy offsets at connection points to create a continuous, jump-free reaction profile.

2. Command Line Syntax Usage: main.py [file1.xyz] [file2.xyz] ... [options]

Options: --pov Export POV-Ray .inc files --bld Export Blender .glb files (sequence) --bld-one Export single Blender .glb file --xyz Export combined .xyz trajectory --log Provide log File -n, --obj_name TEXT object name, default "mol" (POV-Ray only) -f, --fname TEXT output file name or base name --split [none|orca|nw|psi4] Generate split script for specific QM package (for --xyz only) -r, --rev INTEGER Indices of files to reverse, e.g. -r 0 -r 2 will reverse first and third file -b, --bridge INTEGER No. of bridging points (default 10) added for smooth transition if RMSD exceeds the threshold -t, --threshold FLOAT RMSD threshold for adding bridging points (default 0.2). --help Show this message and exit.

Key Arguments: • files: List of XYZ files in chronological order (e.g., edu_to_ts.xyz ts_to_prod.xyz). • --output / -o: Filename for the merged trajectory (Default: combined_trj.xyz). • --reverse [index]: Manually force-reverse a specific segment (rarely needed due to Auto-Flip).

3. Advanced Export Options MolAlign can trigger high-end visualization exports directly from the console: • --pov: Generates a POV-Ray scene file for raytracing. • --blender-multi: Exports each frame as an individual .glb file and creates an import_and_animate.py  script for Blender. • --blender-one: Exports the entire trajectory as a single .glb file and a setup_anim.py script.

4. The "Split & Run" Workflow After a successful alignment, MolAlign offers to create a Quantum Chemistry Bridge:

   1. Split Template: A pre-configured _split.py script is generated.
   2. Customization: Open _split.py to adjust the ORCA_HEADER (Method, Basis Set, etc.).
   3. Execution: Run the script to generate individual .inp files and a .sh batch wrapper for your cluster.

5. Understanding the Output During execution, MolAlign provides real-time feedback: • Atom re-ordering detected: Indicates that the mapping algorithm corrected inconsistent atom indices. • Average RMSD: Shows the quality of the fit between segments. • Warning: High RMSD: If RMSD > 0.1 Å, check if the segments actually share the same chemical "anchor" or if a wrong file was provided.

Troubleshooting: Blender Integration If you are using the Blender export scripts: 1.Import: Import the generated .glb file(s) into Blender. OneFile Mode (--bld-one): Produces a single file containing meshes for all time frames. MultiFile Mode (--bld): Produces individual .glb files for each trajectory point. 2. Scripting: Switch to the Scripting Tab in the Blender top navigation bar. 3. Setup: Open the generated Python script (e.g., import_and_animate.py) and click Run Script. This initializes the animation and material links. 4. Timeline: Your reaction path is now sequenced on the Blender timeline. Press Space to play the animation. 5. Customization: Use the 'Dummy_mol' object to modify surface properties (e.g., Metallic, Roughness, Transmission) via the Shader Editor. Use the 'Trajectory_Control' object to globally adjust the position, rotation, and scale of the entire molecule chain.

6. Examples:

Example 1: 2-Chlorocyclohexane Ring Flip (NWChem Workflow) B3LYP/6-31G, [1] Pathway Description: This example constructs the complete reaction pathway for the cyclohexane ring flip using NWChem IRC output files. The required input geometries and NWChem files are provided in the /nwchem directory. Command Line Execution: To merge the segments and generate the visualization files, run: python3 ../../main.py 2.irc.fxyz 2.irc.bxyz 4.irc.fxyz 4.irc.bxyz 6.irc.fxyz 6.irc.bxyz --xyz --pov -n cyhex --fname Cyhex --log Parameters Explained: --xyz: Generates the combined trajectory file. --pov: Creates the POV-Ray include file. -n cyhex: Defines the prefix for the molecule array in POV-Ray (accessible via cyhex[i]). --fname Cyhex: Sets the base filename for all output files. --log: Generates a detailed processing log. Results: Cyhex.xyz: The full, combined reaction trajectory. Cyhex.inc: A POV-Ray [5] include file containing all structures. You can call specific frames in your .pov file using the cyhex array. combine all rendered frames e.g. with FFmpeg [6] Cyhex.log: Log file documenting the alignment and merging process. Visualization: See test1.pov for a ready-to-render setup using the generated include file.

to generate the corresponding Blender [4] input use: 
python3 ../../../main.py ../{2.irc.fxyz,2.irc.bxyz,4.irc.fxyz,4.irc.bxyz,6.irc.fxyz,6.irc.bxyz} --xyz --bld-one --fname Cyhex --log 

[1] E. Aprà, D. Mejía-Rodríguez, et al., "NWChem: Recent and Ongoing Developments", J. Chem. Theory Comput., 19, 7077–7096 (2023). doi: 10.1021/acs.jctc.3c00421.

Example 2: Addition of Methyl Carbene to Propene (Splitting for BatchMol) PBE0/def2-SVP, [2] Pathway Description: This example focuses on the radical attack of methyl carbene on propene. The required IRC trajectory is provided as ts1.irc_IRC_Full_trj.xyz. Command Line Execution: To process the trajectory and prepare it for further quantum chemical calculations:

python3 ../../main.py ts1.irc_IRC_Full_trj.xyz --fname ts1 --log --xyz --split orca

Workflow & Integration:
Splitting: The --split orca flag generates a dedicated Python script: ts1_split.py.
Input Generation: Run ts1_split.py to automatically create individual ORCA input files for every single 
point along the trajectory.
Batch Processing: These inputs are used to obtain molden files for each step, which can then be 
processed with BatchMol.

Result:
Allows for high-resolution animation of electronic properties, such as tracking the radical center or 
spin density throughout the entire reaction path.

[2] F. Neese, "Software update: the ORCA program system — Version 6.0", Wiley Interdiscip. Rev.: Comput. Mol. Sci., 15, e70019 (2025). doi: 10.1002/wcms.70019.

Example 3: 1-5-H-Shift (Splitting for BatchMol) B3LYP/cc-pVDZ Pathway Description: This example demonstrates the hydrogen migration between the terminal methyl group and the oxygen atom of but-2-en-1-one. It includes input and output files for TS optimization and IRC calculations performed with PSI4. MolAlign was used to generate: irc_split.py: A script to create .molden and .fchk files for BatchMol (enabling ESP or MO visualization along the pathway). Blender Assets: Individual .glb files for each step of the pathway, including an irc_animate.py script for automated processing in Blender [4]. POV-Ray Files [5]: An .inc file containing a molecule array over the reaction path, along with the corresponding input/ini files and the final rendered MP4 video [6]. Blender glb Files (Multi): import all .glb files (glb.tar.gz) in Blender and process using the 'import_and_animate.py' [3] D. G. A. Smith, L. A. Burns, et al., "Psi4 1.4: Open-source software for high-throughput quantum chemistry", J. Chem. Phys., 152, 184108 (2020). doi: 10.1063/5.0006002.

Example 4: Rearrangement of Protonated COT to Methyl-Tropylium (Atom Reordering) (PBE0/def2-SVP RIJK Def2/JK) [2]

Pathway Description: This example demonstrates the complex rearrangement of the protonated cyclooctatetraene (COT) cation into the methyl-tropylium cation via a stable intermediate. All required ORCA input files and transition state geometries are located in the /orca directory.

Workflow in MolAlign: Challenge: The two reaction steps use different atom numbering/ordering, which normally prevents seamless merging. Note: due to poor RMSD 10 bridging points have been interpolated to prevent any jumps during the animation python3 ../../main.py ts14xyz ts43xyz -f irc --log --bld-one

Export & Rendering: [4], [5], [6] The export and rendering process utilizes a Blender template, movie_template.blend, which provides pre-configured lighting and cameras for visualizing the irc.glb trajectory data. After importing the file, the script import_and_animate.py links the molecular meshes to the animation timeline, with optional adjustments available for global scale and material properties to produce a finalized render.

[2] F. Neese, "Software update: the ORCA program system — Version 6.0", Wiley Interdiscip. Rev.: Comput. Mol. Sci., 15, e70019 (2025). doi: 10.1002/wcms.70019.

Rendering Software:

[4] Blender Foundation (2026). Blender (Version 5.1): Cycles Rendering Engine [Computer software]. Retrieved from blender.org [5] POV-Ray Team (2013). Persistence of Vision Raytracer (Version 3.7) [Computer software]. GNU Affero General Public License. Retrieved from povray.org [6] Tomar, S. (2006). Converting video formats with FFmpeg. Linux Journal, 2006(146), 10.

Installation

1. Clone the repository git clone https://github.com cd MolAlign

2. Install dependencies (using a VENV is recommended) pip install -r requirements.txt

   Requirements Python 3.x PySide6 PyScf ....

Usage

python3 main.py

Note: Precompiled executables for macOS, Linux arm64, and Linux x64 are available under 'releases'.

License

This project is licensed under the MIT License - see the LICENSE file for details.