BULMA

BULMA = Batch Utilities for Log parsing, hessian Matrix & Automation

BULMA is a command-line Python utility. It is built around one main script and supports three broad categories of tasks:

Extracting data from calculations
Generating new input files for Gaussian, ORCA, and Q-Chem
Parsing molecular dynamics trajectories

The tool is especially useful when you need to move quickly between quantum chemistry packages, reuse geometries and velocities, or convert outputs into formats compatible with other analysis tools such as Flying Nimbus.

Table of Contents

What BULMA does

BULMA combines several quantum chemistry tasks into a single CLI.

Core capabilities

Extract lower-triangular Hessians from:
- Gaussian16 output
- ORCA .hess files
- Q-Chem HESS files
Extract optimized geometries from:
- Gaussian output
- ORCA output
- Q-Chem output
Generate new input files for:
- Gaussian optimization and frequency jobs
- ORCA optimization and frequency jobs
- Q-Chem optimization, frequency, and AIMD jobs
Generate molecular dynamics inputs for:
- Gaussian BOMD
- ORCA QMD
- Q-Chem AIMD
Parse MD output and trajectory into formats that can be reused later
Export trajectories compatible with the flying_nimbus code

In short, BULMA is a workflow glue tool: it helps you move data between electronic structure calculations, geometry files, MD trajectories, and post-processing.

Supported workflows

Workflow	Gaussian	ORCA	Q-Chem
Hessian extraction	Yes	Yes	Yes
Geometry extraction	Yes	Yes	Yes
Optimization input generation	Yes	Yes	Yes
Frequency input generation	Yes	Yes	Yes
BOMD / AIMD / QMD input generation	Yes	Yes	Yes
MD trajectory parsing	Yes	Yes	Yes
flying_nimbus trajectory output	Yes	Yes	Yes

Project structure

The current project is implemented as a single script:

bulma.py

The script handles all supported modes through command-line flags. Different behaviors are selected with mutually exclusive options such as:

--opt
--freq
--orca-opt
--orca-freq
--dyn
--orca-qmd
--qchem-opt
--qchem-opt-freq
--qchem-qmd
--parse-dyn
--parse-orca-qmd
--parse-qchem-qmd
--extract-geo
--orca-hess
--qchem-hess

Requirements

Minimum

Python 3
Standard Python library modules used by the script:
- argparse
- pathlib
- re
- sys

Optional but required for some MD parsing paths

numpy

numpy is used in the Gaussian BOMD parsing branch when converting coordinates, weighted velocities, and energies into array form.

Installation

Clone the repository

git clone https://github.com/giacomande95-oss/FLYINGNIMBUS_GUI.git
cd Bulma_terminal_version

Run directly

python bulma.py --help

Optional virtual environment

python -m venv .venv
source .venv/bin/activate
pip install numpy

If you only use Hessian extraction or input generation, you may not need any extra package beyond Python itself. For Gaussian BOMD parsing, install numpy.

Quick start

1. Extract a Gaussian Hessian

python bulma.py job.out

This writes:

Hessian.out
Hessian_flat.out

2. Generate a Gaussian optimization input from an XYZ file

python bulma.py geo.xyz --opt

This writes:

geom.com

3. Extract the final optimized geometry from an output file

python bulma.py opt.out --extract-geo

This writes:

geo_opt.xyz

4. Generate ORCA optimization input

python bulma.py geo.xyz --orca-opt

This writes:

geom.inp

5. Parse Gaussian BOMD output and write a flying_nimbus trajectory

python bulma.py dyn.out --parse-dyn --inizio 1 --fine 2500 --xyz geo.xyz --nimbus-traj

General command syntax

BULMA takes one positional argument:

python bulma.py <input_file> [options]

The meaning of <input_file> depends on the selected mode.

Examples

In default mode, <input_file> is usually a Gaussian output file for Hessian extraction.
With --opt, --freq, --orca-opt, --orca-freq, --dyn, --qchem-*, <input_file> is an XYZ geometry file.
With --orca-hess, <input_file> is an ORCA .hess file.
With --qchem-hess, <input_file> is a Q-Chem HESS file.
With --parse-qchem-qmd, <input_file> is a Q-Chem AIMD/QMD .out file.

Hessian extraction

BULMA writes Hessians in two different output forms:

Matrix-style lower-triangular text output
Flattened one-column vector output

Both outputs use Fortran D exponent notation.

Default output names

Matrix file: Hessian.out
Flat vector: Hessian_flat.out

You can change them with:

-m / --matrix-out
-v / --vector-out

Gaussian Hessian extraction

This is the default behavior when no mutually exclusive generation or parsing flag is used.

BULMA scans the output for the block between:

Force constants in Cartesian coordinates
Final forces over variables

and then reconstructs the lower triangular Hessian and writes both outputs.

Basic example

python bulma.py gaussian_freq.out

Custom output names

python bulma.py gaussian_freq.out \
  --matrix-out my_hessian.out \
  --vector-out my_hessian_flat.out

What gets written

my_hessian.out contains rows where row r has exactly r values
my_hessian_flat.out contains the same values as a one-column vector
The flat vector file begins with two blank lines

Typical use case

Use this mode when the code expects a lower-triangular Hessian or a flattened vector in Fortran-style notation.

ORCA Hessian extraction

Use --orca-hess when the input file is an ORCA .hess file.

BULMA reads the ORCA Hessian block starting at $hessian, reconstructs the full symmetric matrix, and converts it into the same lower-triangular BULMA format used elsewhere.

Basic example

python bulma.py job.hess --orca-hess

Custom outputs

python bulma.py job.hess --orca-hess \
  -m orca_hessian.out \
  -v orca_hessian_flat.out

Output behavior

Full ORCA matrix is parsed internally
Output is converted to BULMA’s lower-triangle convention
Exponents are written in D format

Q-Chem Hessian extraction

Use --qchem-hess when the input file is a Q-Chem HESS file.

BULMA looks for a block shaped like:

$hessian
Dimension N
...
$end

It then reads the lower triangle, validates the expected number of elements, and writes the same two output files as for Gaussian and ORCA.

Basic example

python bulma.py HESS --qchem-hess

Custom outputs

python bulma.py HESS --qchem-hess \
  -m qchem_hessian.out \
  -v qchem_hessian_flat.out

Geometry extraction

Use --extract-geo to extract the final geometry from a finished calculation.

Default output:

geo_opt.xyz

Override with:

--geo-out my_geometry.xyz

How BULMA detects the engine

BULMA automatically selects the extraction strategy depending on the file content:

Gaussian: last Standard orientation: block
Q-Chem: last Standard Nuclear Orientation (Angstroms) block
ORCA: last CARTESIAN COORDINATES (ANGSTROEM) block after THE OPTIMIZATION HAS CONVERGED

Gaussian geometry extraction

For Gaussian outputs, BULMA extracts coordinates from the last Standard orientation: block.

Because Gaussian standard orientation blocks do not contain the element symbols in the final XYZ, BULMA uses an XYZ template to recover the atomic symbols and ordering.

Default template

geo.xyz

Example

python bulma.py opt.out --extract-geo --xyz-template geo.xyz

Custom output

python bulma.py opt.out --extract-geo \
  --xyz-template geo.xyz \
  --geo-out extracted.xyz

Important note

For Gaussian geometry extraction, the template file must contain the same atoms in the same order as the calculation.

ORCA geometry extraction

For ORCA outputs, BULMA finds the optimization convergence marker and then extracts the last Cartesian block in Ångström units.

Example

python bulma.py orca_opt.out --extract-geo --geo-out orca_final.xyz

No template is needed because ORCA prints element symbols directly in the coordinate block.

Q-Chem geometry extraction

For Q-Chem outputs, BULMA reads the last Standard Nuclear Orientation (Angstroms) block.

Example

python bulma.py qchem_opt.out --extract-geo --geo-out qchem_final.xyz

No template is required.

Input generation

BULMA can generate new job inputs directly from an XYZ file.

These modes share a common set of ab initio options.

Shared ab initio options

--BS            Basis set                (default: Def2TZVP)
--THEORY        Electronic structure method (default: B3LYP)
--convergence   Optimization keyword     (default: VeryTight)
--Nproc         Number of processors     (default: 48)
--mem           Memory                   (default: 300Gb)
--charge        Total charge             (default: 0)
--mult          Spin multiplicity        (default: 1)

Gaussian input generation

Gaussian optimization input

Use --opt to generate geom.com.

python bulma.py geo.xyz --opt

Output

geom.com

Default route details

The generated input includes:

EmpiricalDispersion=GD3BJ
Opt=(CalcAll,MaxCycles=200,<convergence>)
int=ultrafine
SCF(XQC,Tight)

Customized example

python bulma.py geo.xyz --opt \
  --THEORY M06-2X \
  --BS Def2TZVP \
  --Nproc 16 \
  --mem 64Gb \
  --charge 1 \
  --mult 2 \
  --convergence Tight

Gaussian frequency input

Use --freq to generate geom_freq.com.

python bulma.py geo.xyz --freq

Output

geom_freq.com

Default route details

The generated frequency input includes:

EmpiricalDispersion=GD3BJ
Freq
Iop(7/33=1)
int=ultrafine
SCF(XQC,Tight)
nosymm

Example

python bulma.py geo.xyz --freq \
  --THEORY B3LYP \
  --BS Def2TZVP \
  --Nproc 24 \
  --mem 128Gb

ORCA input generation

ORCA optimization input

Use --orca-opt to generate geom.inp.

python bulma.py geo.xyz --orca-opt

Output

geom.inp

ORCA optimization + frequency input

Use --orca-freq to generate geom_freq.inp.

python bulma.py geo.xyz --orca-freq

Output

geom_freq.inp

Default ORCA behavior

BULMA maps some generic defaults into ORCA-style settings:

If --BS is left at the global default Def2TZVP, ORCA input uses Def2-TZVPD
If --Nproc is left at the global default 48, ORCA input uses 20
If --mem is left at the global default 300Gb, no %maxcore line is written
Convergence (--convergence) is translated into ORCA optimization keywords such as:
- VeryTight → VERYTIGHTOPT
- Tight → TIGHTOPT
- Normal → OPT

Example

python bulma.py geo.xyz --orca-opt \
  --THEORY B3LYP \
  --BS Def2TZVP \
  --Nproc 12 \
  --mem 48Gb \
  --charge 0 \
  --mult 1 \
  --convergence VeryTight

What is written

The ORCA input includes:

keyword line with method, dispersion, basis, SCF keyword, and job type
%PAL NPROCS ... END
optional %maxcore
%SCF with MAXITER 500
%geom with MAXITER 500
Cartesian geometry block in XYZ style

Q-Chem input generation

BULMA supports multiple Q-Chem generation modes.

1. Single-job optimization input

Use --qchem-opt-single.

python bulma.py geo.xyz --qchem-opt-single

Output:

opt.inp

2. Single-job frequency input

Use --qchem-freq.

python bulma.py geo.xyz --qchem-freq

Output:

freq.inp

3. Multi-job optimization input

Use --qchem-opt.

python bulma.py geo.xyz --qchem-opt

Output:

opt.inp

This creates a chained Q-Chem workflow that starts with a frequency job and then launches an optimization that reads the Hessian and SCF guess.

4. Multi-job optimization + final frequency input

Use --qchem-opt-freq.

python bulma.py geo.xyz --qchem-opt-freq

Output:

opt-freq.inp

This creates a three-stage input:

Initial frequency job
Optimization reading Hessian and guess
Final frequency job reading the SCF guess and printing vibrational analysis data

Q-Chem basis naming

BULMA automatically maps:

Def2TZVP -> def2-TZVP

when writing Q-Chem inputs.

Example

python bulma.py geo.xyz --qchem-opt-freq \
  --THEORY B3LYP \
  --BS Def2TZVP \
  --charge 0 \
  --mult 1

Dynamics and MD workflows

BULMA can both generate MD inputs and parse MD outputs.

Gaussian BOMD input generation

Use --dyn to generate a Gaussian BOMD input file.

Basic example

python bulma.py geo.xyz --dyn

Default output:

dyn.com

Default supporting files

By default, BULMA expects a velocity file named:

velocity_gau.xyz

Override it with:

--vel-file my_velocities.xyz

Additional options

--stepsize   BOMD StepSize   (default: 2000)
--npoints    BOMD MaxPoints  (default: 2500)
--dyn-out    Output filename (default: dyn.com)
--chk        Checkpoint name (default: dyn.chk)

Example

python bulma.py geo.xyz --dyn \
  --vel-file velocity_gau.xyz \
  --stepsize 2000 \
  --npoints 5000 \
  --dyn-out dyn.com \
  --chk dyn.chk

Notes

Velocities are appended after the geometry block
BULMA writes the separator line 0 before the velocity section
The script expects one velocity triplet per atom

ORCA QMD input generation

Use --orca-qmd to generate both:

an ORCA QMD input file
an ORCA MD restart file

Basic example

python bulma.py geo.xyz --orca-qmd

Default outputs

If the XYZ file is geo.xyz, BULMA writes:

geo_qmd.inp
geo_qmd.mdrestart

Default supporting file

velocity_orca.xyz

Override it with:

--orca-vel-file my_velocity.xyz

Velocity units

You can specify whether the ORCA velocity file uses:

au (default)
angfs

with:

--orca-vel-unit au
--orca-vel-unit angfs

Example

python bulma.py geo.xyz --orca-qmd \
  --orca-vel-file velocity_orca.xyz \
  --orca-vel-unit au \
  --qmd-timestep 0.20 \
  --qmd-run 2501 \
  --qmd-prefix test_run

This writes:

test_run_qmd.inp
test_run_qmd.mdrestart

Notes

The restart writer converts au velocities into Å/fs when needed
The MD input enables position and velocity dumps with stride 1
The thermostat is set to none
Restart mode is explicitly enabled in the %md block

Q-Chem AIMD/QMD input generation

Use --qchem-qmd to generate a Q-Chem AIMD input.

Basic example

python bulma.py geo.xyz --qchem-qmd

Default files

Input XYZ:

positional argument, e.g. geo.xyz

Default velocity file:

velocity.xyz

Default output:

dyn.inp

Q-Chem AIMD-specific options

--qchem-vel-file   Velocity file      (default: velocity.xyz)
--qchem-qmd-out    Output filename    (default: dyn.inp)
--qchem-timestep   Time_step          (default: 8)
--qchem-steps      aimd_steps         (default: 2500)
--qchem-print      aimd_print         (default: 1)

Example

python bulma.py geo.xyz --qchem-qmd \
  --qchem-vel-file velocity.xyz \
  --qchem-qmd-out dyn.inp \
  --qchem-timestep 8 \
  --qchem-steps 5000 \
  --qchem-print 1

Notes

Velocities are written without unit conversion
The $velocity block contains one (vx vy vz) triplet per atom
The generated $rem section sets JOBTYPE = aimd
AIMD_METHOD defaults to bomd
DFT_D = D4
no_reorient = true
sym_ignore = true

Trajectory parsing

BULMA supports parsing output from multiple engines into trajectory formats suitable for visualization, energy analysis, or workflows such as flying_nimbus.

Parsing Gaussian BOMD output

Use --parse-dyn to parse Gaussian BOMD output.

Required arguments

--parse-dyn
--inizio <start_step>
--fine <end_step_exclusive>
--xyz <reference_geometry.xyz>

Optional arguments

--gout       Explicit Gaussian output file
--vel        Fallback velocity file
--output     Basename for written files (default: parsed_log)
--movie      Also write coordinates-only movie XYZ
--total      Also write energies file
--scale      Shift Epot and Etot by --Emin
--Emin       Minimum energy used with --scale
--nimbus-traj Print the trajectory for Flying Nimbus 
--nimbus-out Trajectory file name for Flying Nimbus (default: parsed_log_traj.xyz)
--Natom      Number of atoms (OPTIONAL, deprecated)

Basic example

python bulma.py dyn.out --parse-dyn \
  --inizio 1 \
  --fine 1001 \
  --xyz geo.xyz

Output files

By default, BULMA writes:

parsed_log_xv.xyz

Optional outputs:

parsed_log.xyz if --movie is used
parsed_log_energies.dat if --total is used
parsed_log_traj.xyz if --nimbus-traj is used and --nimbus-out is not provided

Example with all major outputs

python bulma.py dyn.out --parse-dyn \
  --inizio 100 \
  --fine 600 \
  --xyz geo.xyz \
  --movie \
  --total \
  --nimbus-traj \
  --output run1

This writes:

run1_xv.xyz
run1.xyz
run1_energies.dat
run1_traj.xyz

What BULMA parses from Gaussian output

It supports step segmentation based on either of these markers:

Summary information for step N
Trajectory Number 1 Step Number N

For each selected step, it attempts to read:

Cartesian coordinates
Mass-weighted Cartesian velocities
EKin, EPot, and ETot when --total is requested

Important note on masses

The Gaussian BOMD parser uses an internal mass database. The current implementation includes:

H
C
O
N
S

If your system contains a different element, you must extend the mass table in the source code. If you are using the precompiled version feel free to write on github and we will do it for you.

Parsing ORCA QMD dumps

Use --parse-orca-qmd to parse ORCA trajectory dump files.

Default input files

trajectory.xyz
velocity.xyz

Override them with:

--orca-traj custom_trajectory.xyz
--orca-vel custom_velocity.xyz

Basic example

python bulma.py dummy_input --parse-orca-qmd

The positional input_file is still required by the CLI, but in this mode BULMA actually reads the trajectory and velocity files given by --orca-traj and --orca-vel. Give it the orca output file name if you feel more comfortable.

Output

By default:

parsed_log_traj.xyz

or whatever basename you set with:

--output myrun

Example with explicit range and Epot output

python bulma.py placeholder --parse-orca-qmd \
  --orca-traj trajectory.xyz \
  --orca-vel velocity.xyz \
  --inizio 10 \
  --fine 500 \
  --output orca_run \
  --epot-out epot.dat

Behavior

Positions are read in Ångström
Velocities are read in Å/fs
BULMA converts velocities to bohr/au_time for flying_nimbus-style output
Potential energies can be parsed from trajectory.xyz comments when available
Output step numbering is renormalized so that the first exported frame becomes step 1

Parsing Q-Chem AIMD output

Use --parse-qchem-qmd when the input file is a Q-Chem AIMD output file.

Basic example

python bulma.py qchem_aimd.out --parse-qchem-qmd

Optional controls

--inizio
--fine
--output
--nimbus-out
--epot-out

Example

python bulma.py qchem_aimd.out --parse-qchem-qmd \
  --inizio 1 \
  --fine 1000 \
  --output qmd_run \
  --epot-out qmd_epot.dat

Behavior

BULMA looks for blocks marked by:

Nuclear coordinates (Angst) and velocities (a.u.)

and matches them to corresponding TIME STEP # sections.

It writes a flying_nimbus-style trajectory where:

positions are in Ångström
velocities are kept in atomic units

If --epot-out is requested, BULMA tries to obtain the potential energy from:

V(Electronic)
otherwise E(Total) - T(Nuclear)

Output step numbering is renormalized so that the first exported frame becomes step 1.

Complete CLI reference

Available options by purpose.

Positional argument

input_file

Meaning depends on the selected mode.

Hessian output control

-m, --matrix-out   Output Hessian matrix file    (default: Hessian.out)
-v, --vector-out   Output Hessian vector file    (default: Hessian_flat.out)

Hessian mode selection

--orca-hess        Extract Hessian from ORCA .hess
--qchem-hess       Extract Hessian from Q-Chem HESS

If neither is used, the default Hessian mode assumes Gaussian output.

Geometry extraction

--extract-geo      Extract final geometry and exit
--geo-out          Output XYZ name               (default: geo_opt.xyz)
--xyz-template     Template XYZ for Gaussian     (default: geo.xyz)

Input generation mode selection

These options are mutually exclusive:

--opt
--freq
--orca-opt
--orca-freq
--dyn
--orca-qmd
--qchem-qmd
--qchem-opt-single
--qchem-freq
--qchem-opt
--qchem-opt-freq

Shared ab initio options

--BS             Basis set              (default: Def2TZVP)
--THEORY         Method                 (default: B3LYP)
--convergence    Opt keyword            (default: VeryTight)
--Nproc          Number of processors   (default: 48)
--mem            Memory                 (default: 300Gb)
--charge         Total charge           (default: 0)
--mult           Spin multiplicity      (default: 1)

Gaussian BOMD generation options

--stepsize       BOMD StepSize          (default: 2000)
--npoints        BOMD MaxPoints         (default: 2500)
--vel-file       Velocity file          (default: velocity_gau.xyz)
--dyn-out        Output filename        (default: dyn.com)
--chk            Checkpoint filename    (default: dyn.chk)

ORCA QMD generation options

--orca-vel-file  Velocity file          (default: velocity_orca.xyz)
--orca-vel-unit  Velocity unit          (choices: au, angfs; default: au)
--qmd-timestep   Timestep in fs         (default: 0.20)
--qmd-run        Number of MD steps     (default: 2501)
--qmd-prefix     Prefix for output files

Q-Chem AIMD/QMD generation options

--qchem-vel-file Velocity file          (default: velocity.xyz)
--qchem-qmd-out  Output filename        (default: dyn.inp)
--qchem-timestep Time_step              (default: 8)
--qchem-steps    aimd_steps             (default: 2500)
--qchem-print    aimd_print             (default: 1)

Gaussian BOMD parsing options

--parse-dyn
-i, --inizio     Starting step
-f, --fine       Ending step (exclusive)
-N, --Natom      Total number of atoms
-g, --gout       Gaussian output override
--xyz            Reference equilibrium xyz
--vel            Fallback initial velocity file
-o, --output     Output basename        (default: parsed_log)
--Emin           Minimum potential energy for scaling (default: 0.0)
--scale          Shift Epot and Etot by Emin
--movie          Write coordinates-only xyz
--total          Write energies file
--nimbus-traj    Write flying_nimbus-compatible trajectory
--nimbus-out     Output filename for nimbus trajectory

ORCA and Q-Chem trajectory parsing options

--parse-orca-qmd
--parse-qchem-qmd
--orca-traj      ORCA trajectory file   (default: trajectory.xyz)
--orca-vel       ORCA velocity file     (default: velocity.xyz)
--epot-out       Output potential energy file

Units and conventions

BULMA works across multiple programs that use different conventions. Understanding the units is important.

Constants used internally

Bohr to Ångström conversion is built in
Atomic time to femtoseconds conversion is built in
Velocity conversions are handled when needed

Common conventions in BULMA outputs

Hessian outputs are written with Fortran D exponents
ORCA trajectory parsing converts velocities from Å/fs to bohr/au_time for flying_nimbus output
Q-Chem QMD trajectory parsing keeps velocities in a.u.
Gaussian BOMD parsing writes:
- an xv file with coordinates and converted velocities
- an optional flying_nimbus trajectory in Å + bohr/au_time

Geometry units

Extracted XYZ files are written in Ångström

Common file naming conventions

Hessian extraction

Hessian.out
Hessian_flat.out

Geometry extraction

geo_opt.xyz

Gaussian generation

geom.com
geom_freq.com
dyn.com

ORCA generation

geom.inp
geom_freq.inp
<prefix>_qmd.inp
<prefix>_qmd.mdrestart

Q-Chem generation

opt.inp
freq.inp
opt-freq.inp
dyn.inp

Parsing outputs

<output>_xv.xyz
<output>.xyz
<output>_energies.dat
<output>_traj.xyz
custom --epot-out file

Typical end-to-end examples

Example 1: Gaussian optimization input from XYZ

python bulma.py ethanol.xyz --opt \
  --THEORY B3LYP \
  --BS Def2TZVP \
  --Nproc 8 \
  --mem 16Gb

Result:

geom.com

Example 2: Extract final Gaussian geometry and reuse it for ORCA

python bulma.py gaussian_opt.out --extract-geo \
  --xyz-template geo.xyz \
  --geo-out gaussian_final.xyz

python bulma.py gaussian_final.xyz --orca-opt \
  --THEORY B3LYP \
  --BS Def2TZVP

Result:

gaussian_final.xyz
geom.inp

Example 3: Generate Q-Chem opt+freq workflow from optimized XYZ

python bulma.py final.xyz --qchem-opt-freq \
  --THEORY B3LYP \
  --BS Def2TZVP \
  --charge 0 \
  --mult 1

Result:

opt-freq.inp

Example 4: Convert ORCA QMD into a flying_nimbus trajectory

python bulma.py dummy.dat --parse-orca-qmd \
  --orca-traj trajectory.xyz \
  --orca-vel velocity.xyz \
  --output nimbus_orca \
  --epot-out epot_orca.dat

Result:

nimbus_orca_traj.xyz
epot_orca.dat

Example 5: Parse Gaussian BOMD and write Nimbus compatible outputs

python bulma.py bomd.out --parse-dyn \
  --inizio 1 \
  --fine 2501 \
  --xyz eq.xyz \
  --movie \
  --total \
  --nimbus-traj \
  --output bomd_analysis

Result:

bomd_analysis_xv.xyz
bomd_analysis.xyz
bomd_analysis_energies.dat
bomd_analysis_traj.xyz

Limitations and important notes

1. Gaussian geometry extraction needs an XYZ template

For Gaussian --extract-geo, BULMA uses --xyz-template to restore element labels and ordering. If the template does not match the output, the extracted XYZ will be incorrect or fail.

2. Gaussian BOMD mass table is limited

The internal mass database currently includes only:

H
C
O
N
S

If your system contains other elements, you must extend the source code in get_masses_cart(). If you are using a precompiled version feel free to contact us on Github.

3. Velocity file sizes must match the atom count

For all generated dynamics inputs and restart files, the number of velocity lines must match the number of atoms in the XYZ geometry.

4. Some CLI modes still require a positional `input_file` even if they mainly read auxiliary files

For example, --parse-orca-qmd uses --orca-traj and --orca-vel, but the CLI still expects a positional first argument.

5. ORCA and Q-Chem defaults are adapted internally

Some defaults are translated to engine-specific settings instead of being copied literally.

Examples:

ORCA default basis becomes Def2-TZVPD
ORCA default processor count becomes 20
Q-Chem default basis string becomes def2-TZVP

Troubleshooting

“Could not find start marker” during Gaussian Hessian extraction

Cause:

The file is not a Gaussian Hessian-containing output
The calculation did not reach the expected section (Error messages?)
The wrong file was passed as input

Fix:

Confirm the file is a Gaussian frequency output containing Force constants in Cartesian coordinates

“Could not find ORCA start marker” or incomplete ORCA Hessian parsing

Cause:

The input is not a valid ORCA .hess file
The file is truncated

Fix:

Use the .hess file rather than the .out
Confirm the $hessian section is complete

“Q-Chem Hessian size mismatch”

Cause:

The HESS file is incomplete or malformed

Fix:

Regenerate the Q-Chem Hessian file
Check for accidental editing or truncation

“Velocity/geometry mismatch”

Cause:

Number of atoms in the XYZ file and velocity file differ

Fix:

Ensure that the velocity file contains one line per atom
Confirm both files refer to the same molecular system

“No MD step markers found” in Gaussian trajectory parsing

Cause:

The Gaussian output does not contain one of the supported step markers
The output is not a compatible BOMD job

Fix:

Confirm the file is a Gaussian BOMD output and that the relevant sections are present

“Atom X not in mass database”

Cause:

The molecule contains an element not hardcoded in get_masses_cart()

Fix:

Add the missing atomic mass to the source code before running the parser again

License

This project is marked in the source with:

SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0

Check the repository for the full license text and any additional usage notes.

Authors

Authors listed in the source:

Giacomo Mandelli, Ph.D., Politecnico di Milano
Giacomo Botti, Ph.D., University of South Carolina