Metadata-Version: 2.4
Name: cathpkg-portico
Version: 2026.0.post3
Summary: Asymptotic classification of transition-state normal modes via projection onto roto-translational internal coordinates
Author-email: David Ferro-Costas <david.ferro@usc.es>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cathedralpkg/portico
Keywords: transition state,normal modes,internal coordinates,fragmentation,computational chemistry
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: ase
Dynamic: license-file

# PORTICO

**P**rojection **O**nto **R**oto-**T**ranslational **I**nternal **CO**ordinates

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

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 **Ω<sub>i</sub> ∈ [0, 1]** measuring the contribution of the
roto-translational subspace. Combined with the dimensionality of the
product channel, the Ω<sub>i</sub> 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

```bash
pip install cathpkg-portico
```

### From GitHub

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

### In a conda environment

```bash
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

```bash
portico -h                       # help
portico --input                  # create an example input file
portico channel.inp              # run the classification
portico channel.inp --plot       # ... and plot the Omega_i weights
portico -v                       # 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

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

# 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.

### Converting Gaussian outputs to gts

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

```bash
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).

### Output

PORTICO prints the Ω<sub>i</sub> projection of every real-frequency normal
mode of the transition state, sorted by weight, and identifies the
transitional modes of the channel. With `--plot`, a bar chart of the
weights is also generated:

```
      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
         ...

```

## 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](https://orcid.org/0000-0002-8365-4047))
