ConeZen

Visualiser for Conical Intersection Branching Planes

---

Conical Intersection Branching Plane Visualization

Conical intersections (CIs) are fundamental mechanistic features that govern the outcomes of virtually all photochemical and photophysical processes in polyatomic molecules. The functional role of a CI is dictated by its local topography; for example, CIs in DNA provide an ultrafast deactivation funnel that ensures photostability, while the CI in retinal acts as a highly efficient chemical switch that initiates vision.

Despite their importance, a significant bottleneck exists in translating the raw numerical data—state energy gradients and nonadiabatic coupling vectors—produced by quantum chemistry software into mechanistic insight. We present ConeZen, an open-source Python package designed to bridge this gap. ConeZen automates the entire analytical workflow, from parsing the output of quantum chemistry packages like SHARC-OpenMolcas to generating quantitative topological descriptors and intuitive 3D visualizations.

By providing a user-friendly command-line interface (CLI) and a flexible API, ConeZen empowers researchers to rapidly characterize and visualize CI topographies, facilitating a deeper understanding of nonadiabatic reaction dynamics.

• 📝Note: ConeZen was tested with the gradients and NAC obtained from SHARC-OpenMolcas interface. The automated extraction feature is specifically designed for the QM.out file generated by this interface. (see SHARC Manual)

---

✨ Key Features

• Automated Analysis

  • Direct QM Output Parsing Automatically extracts the required gradients and nonadiabatic coupling (NAC) vectors directly from sharc-molcas QM.out files. Just specify the file and the states of interest (e.g., S1, T2), and ConeZen handles the rest.
  • Topological Analysis Computes key CI descriptors from the vector data:
    • The strength or pitch ( $\delta_{gh}$ )
    • The asymmetry ( $$\Delta_{gh}$$ )
    • The relative tilt and tilt heading $$\sigma$$ , $\theta_s$ respectively.
      This saves researchers from tedious manual calculations and allows for rapid classification of CIs as peaked, sloped, single-path, or bifurcating.

• High-Quality Visualization
  Generates publication-ready 3D surface plots using Matplotlib. The plots are fully customizable and can be exported in various high-resolution formats (PNG, PDF, SVG) for direct inclusion in presentations and publications.

• Animations
  Creates animated GIFs or MP4s showing a 360° rotation of the 3D surface. These are especially useful for presentations and for gaining a more intuitive feel for the three-dimensional structure of the potential energy surfaces around the degeneracy.

• Dual Interface
  Offers both an easy-to-use interactive Command-Line Interface (CLI) and an importable Python library (API). This provides flexibility for both quick, interactive analyses and more complex, scripted workflows or integration into larger computational chemistry pipelines.

• Minimal Dependencies
  Built on a small, robust stack of standard scientific libraries (NumPy, Pandas, Matplotlib), making installation straightforward and avoiding dependency conflicts.

---

🚀 Installation

Follow these steps to install ConeZen from the source code.

1. Install Miniconda

If you don't have Conda installed, we recommend installing [Miniconda](https://docs.conda.io/en/latest/miniconda.html), a minimal installer for Conda.

2. Clone the Repository

First, clone the repository to your local machine and navigate into the directory.

git clone https://github.com/Kalpa08/ConeZen.git
cd ConeZen

3. Create a Conda Environment

It's recommended to create a dedicated environment to manage dependencies. The following commands will create and activate a new environment named conezen_env with Python 3.11.

# Create and activate a virtual environment (optional but recommended)
conda create --name conezen_env python=3.11
conda activate conezen_env 

4. Install the Package

Finally, install ConeZen and all its required dependencies using pip. The . tells pip to install the package located in the current directory.

# Install ConeZen
pip install build
pip install .

That's it! ConeZen is now installed in your environment and ready to use.

System Dependencies (Required for Animations)

To create and save animations as MP4 files, you must have FFmpeg installed and accessible in your system's PATH.

• Windows: Download the binaries from the official FFmpeg site and add the bin folder to your system's PATH.

• macOS: Install using Homebrew:

brew install ffmpeg

Linux (Ubuntu/Debian): Install using the package manager:

sudo apt-get install ffmpeg

---

🧪 Usage

ConeZen can be run in two ways: through the command line or as a Python library.

1. Command-Line Interface (CLI)

The easiest way to use ConeZen is to run it from your terminal. Running conezen initiates a user-friendly, step-by-step process. The tool will first request the file paths for the gradients of the two electronic states, the nonadiabatic coupling vector, and the molecular geometry. It then interactively prompts for plotting and saving options.

conezen

The interactive session will look like this:

Workflow 1: Automated Extraction (Recommended)

This is the recommended and easiest workflow.

============================================================
    ConeZen: Conical Intersection Branching Plane Visualization
============================================================
...
(Do you want to automatically extract gradients and NACs from a QM output file? (only for sharc-molcas output QM.out file) [y/n]: y
Enter the source QM file name (default: QM.out):
Enter the total number of singlet states (default: 20): 5
Enter the total number of triplet states (default: 20): 5
Enter the lower state (e.g., S2): s2
Enter the upper state (e.g., S3): s3
✅ Successfully extracted and saved 'S2_gradient.out'
✅ Successfully extracted and saved 'S3_gradient.out'
✅ Automatically extracted and saved 'NAC_S2_S3.out'
Enter the energy of the intersection point (Hartree) (default: 0):
...
✅ Key quantities calculated.
Save branching plane key quantities to a file? [y/n]: y
Enter filename for parameters (default: ci_parameters.txt):
...
Show 3D surface plot now? [y/n]: y

Workflow 2: Manual File Input

Use this if you have your gradient and NAC vectors in separate files (gradientA.out, NAC.out, etc.).

============================================================
    ConeZen: Conical Intersection Branching Plane Visualization
============================================================
...
Enter the gradient file name for State A (default: gradientA.out):
Enter the gradient file name for State B (default: gradientB.out):
Enter the NAC vector file name (default: NAC.out):
Enter the xyz file name for atom labels (default: orca.xyz):
Enter the energy of the intersection point (Hartree) (default: 0):
...
✅ Key quantities calculated.
Save branching plane key quantities to a file? [y/n]: y
Enter filename for parameters (default: ci_parameters.txt):
...
Show 3D surface plot now? [y/n]: y

Workflow 3: Direct Parameter Input

Use this advanced workflow if you have already calculated the orthonormal branching plane vectors (x_hat and y_hat) and the key ci parameters. The script will skip all calculations and proceed directly to generating the surfaces.

(Do you want to automatically extract... [y/n]: n
Do you have the raw gradient and non-adiabatic coupling vectors... [y/n]: n
➡️  Entering manual mode: Provide orthonormal vectors (x_hat, y_hat) and CI parameters directly.

2. Python API

You can also import ConeZen into your own Python scripts or a Jupyter Notebook for more advanced workflows. This gives you direct access to the underlying data structures and plotting functions for custom analysis.

Proposed New API Example:

# example_script.py

import matplotlib.pyplot as plt
from conezen import ConeZenAPI

# 1. Initialize the API
# This creates an instance of the main API class.
cz_api = ConeZenAPI()

try:
    # 2. Load data from your files
    # The API uses the same file loading logic as the CLI.
    cz_api.load_data_from_files(
        grad_a_path='gradientA.out',
        grad_b_path='gradientB.out',
        nac_path='NAC.out'
    )

    # 3. Perform the calculations
    # These methods call the core algorithms to get the CI parameters
    # and then compute the energy surfaces.
    cz_api.calculate_parameters()
    cz_api.compute_surfaces(E_X=0.0) # E_X is the energy at the crossing point in Hartree

    # 4. Retrieve and use the results
    # You can get the calculated parameters and vectors for your own analysis.
    parameters = cz_api.get_parameters()
    vectors = cz_api.get_vectors()

    print("--- Calculation Results ---")
    print(f"Sigma (σ): {parameters['sigma']:.6f}")
    print(f"Theta_s (θ_s) in degrees: {parameters['theta_s_rad'] * 180 / 3.14159:.6f}")
    print(f"Shape of x_hat vector: {vectors['x_hat'].shape}")
    print("-------------------------")

    # 5. Generate a static 3D plot
    # The plot method returns the matplotlib figure and axes objects
    # for further customization if needed.
    print("Generating static plot...")
    fig, ax = cz_api.plot(elev=30, azim=-45) # You can override default view angles
    ax.set_title("PES via ConeZen API")
    plt.show()

    # 6. Generate and save an animation
    # The animate method creates a rotating GIF or MP4 video.
    print("Generating MP4 animation...")
    cz_api.animate('ci_animation.mp4')
    print("✅ Animation saved to ci_animation.mp4")

except (FileNotFoundError, RuntimeError) as e:
    print(f"An error occurred: {e}")

📄 Input File Format

ConeZen can now work directly with QM.out files from SHARC-OpenMolcas, but it also supports manually prepared text files.

• Source Quantum Chemistry File (QM.out):

  • This is the primary input for the new automated workflow.
  • ConeZen searches this file for the specific headers corresponding to the requested electronic states (e.g., m1 1 s1 3 ms1 0 for the S2 gradient) to extract gradient and NAC vectors.

• Gradient and NAC Files (gradientA.out, gradientB.out, NAC.out):

  • These files are generated automatically when using the extraction workflow or can be provided manually.
  • The first line is treated as a header and is skipped.
  • Subsequent lines should contain the Cartesian vector components (x, y, z) for each atom.
  • The script reads the first three numeric values on each line. Any additional text (like atom symbols) is ignored.

• Geometry File (.xyz):

  • A standard XYZ file format is used to add atom labels to the output vector files.
  • The first two lines (number of atoms and a comment line) are skipped as per the standard.

Example gradientA.out:

7 3 ! m1 1 s1 3 ms1 0
 1.538527244911E-002  2.700614793356E-002 -1.774304949876E-002
 4.842665117426E-004 -6.611115362176E-005 -1.307997738720E-003
 6.585259497396E-004 -9.263239120174E-004  3.094972603908E-004
 ...

Example NAC.out:

7 3 ! m1 1 s1 3 ms1 0   m2 1 s2 4 ms2 0
-1.577934889249E+002  4.936445290015E+001 -6.162157991488E+001 
-5.923796065802E+000  1.911233859294E+000 -2.389064178526E+000 
 2.196082257074E+001  4.671921146048E+001 -2.720461218524E+001
 ...

Example orca.xyz:

7
Coordinates from ORCA-job orca
 C   -1.67927099317952     -0.08967085472111      1.37125703628325
 H   -1.55677664790204     -0.76202298903129      0.52236315843451
 ...

📤 Output

The CLI tool can generate several useful output files in your working directory:

• S2_gradient.out, NAC_S2_S3.out, etc.: The gradient and NAC files automatically extracted from the source QM.out file.
• ci_parameters.txt: A text file containing the calculated topological quantities ($\delta_{gh}$, $$\Delta_{gh}$$ , σ , $\theta_s$). This provides a quick human-readable summary of the CI's characters.
• x_vectors.out, y_vectors.out: The orthonormal branching plane vectors $\hat{x}$ and $\hat{y}$.
• conical_intersection.png: A high-resolution image of the 3D plot. The plot is saved with a transparent background and tight bounding box, making it easy to incorporate into other documents.

🧾 Citing ConeZen

If you use ConeZen in your research, please cite the accompanying paper. Your citation allows us to track the software's impact and helps support its continued development.

@software{conezen,
  author  = {Kalpajyoti Dihingia and Biswajit Maiti},
  title   = {ConeZen: Visualiser for conical intersection branching planes},
  year    = 2025,
  publisher = {Zenodo},
  version = {v0.1.4},
  doi     = [10.5281/zenodo.16161336](https://doi.org/10.5281/zenodo.16161336)
}

---

⚖️ License

Distributed under the GNU GPL v3.0. See the LICENSE file for details.

---

🙏 Acknowledgments

• Developed at Banaras Hindu University, Varanasi, India.
• Based on the theoretical framework described in: J. Chem. Theory Comput. 2016, 12(8), 3636–3653. DOI: 10.1021/acs.jctc.6b00384

---

For full metadata and citation, see CITATION.cff and .zenodo.json.

---

🤝 Contributions

Contributions are welcome! Please see CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting issues or pull requests.