PORTICO

Projection Onto Roto-Translational Internal COordinates

+------------------------------------+
|                   _   _            |
|  _ __   ___  _ __| |_(_) ___ ___   |
| | '_ \ / _ \| '__| __| |/ __/ _ \  |
| | |_) | (_) | |  | |_| | (_| (_) | |
| | .__/ \___/|_|   \__|_|\___\___/  |
| |_|                                |
+------------------------------------+

PORTICO is a Python program for the asymptotic classification of transition-state normal modes. For a dissociation channel

R  →  TS‡  →  P1 + P2

some of the normal modes that are vibrational at the saddle point evolve asymptotically into rotations or translations of the product fragments. PORTICO identifies these transitional modes automatically, with no manual inspection of normal-mode animations and no propagation of the reaction path toward the products.

How it works

PORTICO builds a redundant internal-coordinate representation of the transition state that explicitly separates two classes of motion:

• {q}v — internal coordinates describing the vibrations of the product fragments (generated automatically for each isolated product and verified for completeness against its Cartesian frequencies);
• {q}t,r — displacement vectors representing the translations and rotations of the fragments embedded in the transition-state geometry.

The transition-state normal modes are expressed in this mixed basis by solving the Wilson GF problem, and each mode i is assigned a scalar projection Ω_i ∈ [0, 1] measuring the contribution of the roto-translational subspace. Combined with the dimensionality of the product channel, the Ω_i values identify the transitional modes — those that correlate with rotations and relative translations of the separating fragments.

Channels leading to atomic, linear, and non-linear fragments are treated on the same footing.

Requirements

• Python ≥ 3.8
• numpy, scipy, matplotlib, ase

Installation

From PyPI

pip install cathpkg-portico

From GitHub

pip install git+https://github.com/cathedralpkg/portico.git

In a conda environment

conda create -n portico python=3.11
conda activate portico
pip install cathpkg-portico

Any of the above installs the portico and gaussian2gts commands in your PATH. Alternatively, the two scripts (portico.py, gaussian2gts.py) are self-contained and can simply be downloaded and run with python3 provided the dependencies are available.

Usage

portico input_file_name          # run the classification

portico -h | --help              # help
portico -g | --ginp              # create an example input file
portico -v | --version           # program version

Input file

# Files with the electronic-structure data (gts format)
file_saddle   TS.gts        # transition state
file_product1 P1.gts        # product fragment 1
file_product2 P2.gts        # product fragment 2

# Name of file for plot (optional; default value shown)
file_plot     omegas.png    # plot file name

# Thresholds (optional; default values shown)
eps_conn 1.30               # bonding threshold
eps_ccic 6.00               # frequency tolerance (cm-1)

# Random seed (optional; useful for reproducibility between executions)
#seed         9876543210    # random seed

# Atom mapping: product atom <--> TS atom (1-based)
product1:
  1 1
  2 2
  3 3
  4 4
end
product2:
  1 5
  2 6
end

The required data for the transition state and for each optimized product are: geometry, Cartesian Hessian, charge/multiplicity and energy, provided in gts format. The atom mapping defines which atom of the transition state corresponds to each atom of the products.

Output

PORTICO prints the Ω_i metrics of every real-frequency normal mode of the transition state and identifies the transitional modes of the channel.

      freq (cm^-1)   Omega_i
    --------------------------
        -1531.2        ifreq   [roto-translational]
         1266.7        0.955   [roto-translational]
         2210.0        0.954   [roto-translational]
          812.1        0.934   [roto-translational]
          715.0        0.907   [roto-translational]
         1644.3        0.706
         1166.2        0.537
         ...

The .gts file format

The .gts format is a plain-text format shared by the programs of the Cathedral package. It stores the electronic-structure data of a single molecular structure: charge, multiplicity, energy, point-group symmetry, Cartesian coordinates, gradient, and Hessian matrix.

Files in this format can be generated from Gaussian output with the gaussian2gts utility distributed with PORTICO.

A .gts file is organized in blocks delimited by start_<block> and end_<block> keywords. Lines beginning with # are comments and are ignored. All quantities are given in atomic units.

start_basic / end_basic

Scalar properties of the structure:

Keyword	Meaning
charge	total charge
multiplicity	spin multiplicity
energy	total electronic energy (hartree)
pointgroup	point group (e.g. C1, C2v)
rotsigma	rotational symmetry number

start_cc / end_cc

One line per atom: the atomic number (as a three-digit integer, e.g. 006 for carbon) followed by the three Cartesian coordinates in bohr.

start_grad / end_grad

The Cartesian energy gradient in hartree/bohr, one atom per line (three components each). For a stationary point the gradient is (numerically) zero; it is required for the analysis at non-stationary points along a reaction path.

start_hess / end_hess

The lower-triangular part of the Cartesian Hessian matrix in hartree/bohr², listed row by row:

F_11, F_21, F_22, F_31, F_32, F_33, ...

The values are written sequentially (any number of values per line); the program reshapes them into the full symmetric 3N x 3N matrix.

Converting Gaussian outputs to gts

The helper script gaussian2gts converts a Gaussian log file (from a freq calculation) into a gts file:

gaussian2gts TS.log        # creates TS.gts
gaussian2gts P1.log        # creates P1.gts
gaussian2gts P2.log        # creates P2.gts

If you use a different electronic-structure package, write an analogous converter producing the gts format (a simple, documented plain-text format; see the header of any generated file).

Citation

If you use PORTICO in your work, please cite:

D. Ferro-Costas, PORTICO: Projection Onto Roto-Translational Internal COordinates — a program for the asymptotic classification of transition-state normal modes, submitted (2026).

License

Distributed under the MIT license. See LICENSE for details.

Author

David Ferro-Costas — Universidade de Santiago de Compostela (ORCID 0000-0002-8365-4047)