Ghostly

Ghostly is a package to perform modification of ghost (dummy) atom bonded terms for alchemical free energy calculations, using the approach described in the paper "Dummy Atoms in Alchemical Free Energy Calculations", available here. These modifications were designed to solve two key issues:

1. To ensure that ghost atoms only give a multiplicative contribution to the partition function, which will cancel when computing double free-energy differences.

2. To avoid spurious coupling between the physical and ghost systems, which can affect the equilibrium geometry of the physical system.

Ghostly implements many extensions beyond the original modification scheme to handle the diversity of perturbations encountered in practice:

• Anchor selection scoring: physical anchor atoms are scored to avoid transmuting or bridge atoms, preventing geometrically inconsistent constraints.
• Ring and sp2 bridge handling: angle stiffening is skipped by default for ring and sp2 bridges, where local geometry already constrains the ghost and 90° stiffening would introduce significant strain. It can be re-enabled via --stiffen-ring-bridges and --stiffen-sp2-bridges.
• Residual term cleanup: a post-processing pass removes mixed improper dihedrals and cross-bridge dihedrals missed by the per-bridge junction handlers, as well as angles where a ghost atom is the central atom and both terminal atoms are physical.
• Mixed dihedral softening: surviving mixed ghost/physical dihedrals can be softened via --soften-anchors to allow ghost groups to reorient and avoid steric clashes at small λ.
• Rotamer stiffening: --stiffen-rotamers replaces rotatable sp3 anchor dihedrals with a stiff single-well cosine to control ghost orientation through flexible bonds.
• Ring-breaking perturbations: adjacent bridges with independent ghost groups retain each other as physical neighbours; angles with a ghost central atom spanning two physical neighbours are replaced by a linear spacer (180°, soft force constant); and angles spanning the ring-making/breaking bond are removed in the state where that bond is absent.

Ghostly is incorporated into the SOMD2 free-energy perturbation engine.

See the examples directory for more details.

Installation

Conda package

Install ghostly directly from the openbiosim channel:

conda install -c conda-forge -c openbiosim ghostly

Or, for the development version:

conda install -c conda-forge -c openbiosim/label/dev ghostly

Installing from source (standalone)

To install from source using pixi, which will automatically create an environment with all required dependencies (including pre-built Sire and BioSimSpace):

git clone https://github.com/openbiosim/ghostly
cd ghostly
pixi install
pixi shell
pip install -e .

Installing from source (full OpenBioSim development)

If you are developing across the full OpenBioSim stack, first install Sire from source by following the instructions here, then activate its pixi environment:

pixi shell --manifest-path /path/to/sire/pixi.toml -e dev

You may also need to install other packages from source, e.g. BioSimSpace:

pip install -e /path/to/biosimspace

Then install ghostly into the environment:

pip install -e .

Testing

You should now have a ghostly executable in your path. To test, run:

ghostly --help

Development

Pre-commit hooks are used to ensure consistent code formatting and linting. To set up pre-commit in your development environment:

pixi shell -e dev
pre-commit install

This will run ruff formatting and linting checks automatically on each commit. To run the checks manually against all files:

pre-commit run --all-files

Usage

Ghostly requires topology and coordinate files for the reference and perturbed molecules as input, along with an optional mapping dictionary that specifies the mapping between atoms in the end states. The molecular inputs can be in any valid file format supported by Sire. The mapping should be a string representation of a dictionary, where the keys are atom indices in the reference state and the values are the corresponding atom indices in the perturbed state. This allows the mapping to be generated programmatically by any suitable external tool.

ghostly --reference reference.* --perturbed.* --mapping '{0: 0, 1: 4, 2: 3, 3: 2, 4: 1}' --log-level debug

Alternatively, you can pass a stream file containing a perturbable BioSimSpace system, which already contains the merged end states, using the --system option.

ghostly --system system.bss --log-level debug

Note

The --system option takes precedence over the --reference and --perturbed options.

When finished, the program will output a BioSimSpace stream file for the perturbable molecule, or AMBER or GROMACS files for the two end states. The format can be specified using the the --output-format option. If you require input for a free-energy perturbation simulation, e.g. a hybrid GROMACS toplogy file, the you can use the stream file with BioSimSpace to generate the required input files. Additionally, the program will output a JSON file summarising the modifications that were made.

Note

When a stream file is used as input, the --mapping option is ignored. and the output will always be a stream file, regardless of the --output-format option.

Please run ghostly --help for more details of other configuration options.