Molecular QM fcc_tools / FCclasses3

Python bindings and Simstack nodes for FCclasses3 and the bundled fcc_tools helpers (input generation and spectrum post-processing).

Nodes

Node	Upstream tool	Role
fcclasses3	fcclasses3	Vibronic spectrum / rate calculation
gen_fcc_state	gen_fcc_state	Build FCclasses state files from QM outputs
gen_fcc_dipfile	gen_fcc_dipfile	Build ELDIP / MAGDIP / NAC files
reconvolute_td	reconvolute_TD	Re-broaden a TD spectrum from corr.dat
reconvolute_ti	reconvolute_TI	Re-broaden a TI spectrum from Bin_Spectrum.dat
convolute_rr	convolute_RR	Convolve resonance-Raman stick / 2D spectra

Option schemas live under models/ and mirror the CLI / input flags from the manuals.

Install

pyproject.toml is the Hatch Python package (nodes and models). It does not build FCclasses3; that needs gfortran, which a normal host install does not provide.

uv pip install .

The Fortran tools (fcclasses3, gen_fcc_state, gen_fcc_dipfile, reconvolute_TD, reconvolute_TI, convolute_RR) are compiled in the Docker image from vendor/fcclasses3-3.0.4.tar.gz. The image installs the Python package from pyproject.docker.

Shared deps install from git (see pyproject.toml / pyproject.docker): molecular_qm_models, molecular_qm_util (develop-ww), simstack (fix-git-pull).

Local Docker image

The Dockerfile builds FCclasses3 3.0.4 (including fcc_tools) from the vendored tarball vendor/fcclasses3-3.0.4.tar.gz with gfortran and system BLAS/LAPACK.

From this repository:

docker build -t molecular-qm-fcctools:latest .

From a simstack-model checkout:

docker build -t molecular-qm-fcctools:latest -f molecular_qm_fcctools/Dockerfile molecular_qm_fcctools

GHCR / Apptainer

On push to main, GitHub Actions builds the Docker image, converts it to a .sif, and publishes both to GHCR:

Kind	Reference
Docker	ghcr.io/simstack/molecular-qm-fcctools:latest
Apptainer SIF	oras://ghcr.io/simstack/molecular-qm-fcctools-sif:latest

On a remote machine with Apptainer, pull the pre-built SIF (no Fortran compiler needed):

# Public package: no login.
# Private package: create a GitHub PAT with read:packages, then:
#   echo "$GHCR_TOKEN" | apptainer registry login -u YOUR_GITHUB_USER --password-stdin docker://ghcr.io

apptainer pull molecular_qm_fcctools.sif \
  oras://ghcr.io/simstack/molecular-qm-fcctools-sif:latest

If you only need the Docker image and will convert locally:

# docker
docker pull ghcr.io/simstack/molecular-qm-fcctools:latest

# or let Apptainer pull the Docker image and write a SIF
apptainer pull molecular_qm_fcctools.sif \
  docker://ghcr.io/simstack/molecular-qm-fcctools:latest

Private GHCR images need docker login ghcr.io (or the Apptainer login above) with a token that has read:packages. Then:

apptainer run molecular_qm_fcctools.sif

2FA-only machines

Interactive gh auth login / browser 2FA will not work on those hosts. Create a classic PAT (or fine-grained token with contents: read and read:packages) on a machine where you can complete 2FA, put it in a file, and download the SIF from the rolling GitHub Release over HTTPS:

# ~/.github_token is a PAT; chmod 600. No interactive 2FA on this host.
curl -fL \
  -H "Authorization: Bearer $(cat ~/.github_token)" \
  -o molecular_qm_fcctools.sif \
  https://github.com/simstack/molecular_qm_fcctools/releases/download/container-sif/molecular_qm_fcctools.sif

If the repository is private, GitHub may 302 through the API. Then:

GH_TOKEN=$(cat ~/.github_token) gh release download container-sif \
  -R simstack/molecular_qm_fcctools \
  -p 'molecular_qm_fcctools.sif'

The same PAT can be used non-interactively for Apptainer/GHCR:

export APPTAINER_DOCKER_USERNAME=YOUR_GITHUB_USER
export APPTAINER_DOCKER_PASSWORD=$(cat ~/.github_token)
apptainer pull molecular_qm_fcctools.sif \
  oras://ghcr.io/simstack/molecular-qm-fcctools-sif:latest

Upstream notes

• FCclasses3: http://www.iccom.cnr.it/en/fcclasses/
• fcc_tools: https://github.com/jcerezochem/fcc_tools