SFRIS: A Systematic Fragmentation-Recombination Approach for Isomer Search

How to use

Install

pip install sfris

Requires Python 3.9+ and a working xTB installation. ORCA, Psi4 (untested), or Gaussian 16 (untested) are optional for DFT refinement.

Configure (once per machine)

sfris config init

Edit ~/.config/sfris/config to set software paths:

[settings] 

XtbPath = /path/to/xtb 

OrcaPath = /path/to/orca 

# Psi4Path = /path/to/psi4 

# GaussianPath = /path/to/gaussian 

NProc = 8 

ScratchDir = /tmp/sfris_scratch 

Run

sfris example CH4O

sfris run CH4O.inp &

Results are written to the ISOMER/ directory. Progress is logged in SFRIS.run.

Final isomers are listed in SFRIS_ISOMER.lis

Commands

sfris run <input>  &     Run isomer search

To stop a running calculation, create a stop file (e.g., touch CH4O.STOP). The calculation will save progress and can be resumed with the same run command.

For full documentation, see the README.

Example: From Installation to Results

Step 1: Create a conda environment

conda create -n sfris python=3.13 -y

conda activate sfris

Step 2: Install SFRIS

pip install sfris

Step 3: Configure software paths

sfris config init

Edit the config file:

nano ~/.config/sfris/config

Example configuration:

[settings]

XtbPath = /path/to/xtb

OrcaPath = /path/to/orca

# Psi4Path = /path/to/psi4

# GaussianPath = /path/to/gaussian

NProc = 8

ScratchDir = /path/to/scratch

Verify:

sfris config

Step 4: Prepare input

Copy a built-in example:

sfris example CH4O

Or create your own input file (e.g., C2H6O.inp):

# C2H6O - Ethanol

0 1

C    -0.047600    0.579400    0.000000

C     1.421400    0.207200    0.000000

O    -0.780200   -0.627500    0.000000

H    -0.337300    1.174200    0.876200

H    -0.337300    1.174200   -0.876200

H     1.711700   -0.387600    0.876200

H     1.711700   -0.387600   -0.876200

H     1.969800    1.152600    0.000000

H    -1.724200   -0.407400    0.000000

Parameters

[CUT]

CutControl = 3, 0.4

[SEARCH]

ConvergenceRounds = 30, auto, auto

[CLUSTER]

MirrorCheck = true

[FILTER]

ScanLimit = 150

AdvOptFilter = 50

[ADVOPT]

[NMA]

[]

Note: The [] end marker is required.

To run xTB screening only (Block 1), remove [ADVOPT] and [NMA].

Step 5: Run

sfris run C2H6O.inp &

The calculation runs in the background. 

Step 6: Monitor progress

tail -f SFRIS.run

To stop the calculation gracefully:

touch C2H6O.STOP

The calculation saves a checkpoint and exits. Resume with the same run command.

Step 7: Results

After completion, the output files are:

SFRIS.run             Log file

SFRIS.sum             Summary

SFRIS_MIN.lis         List of optimized structures with energies

SFRIS_ISOMER.lis      Constitutional isomer groups

ISOMER/               Final isomer structures (.xyz)

MIN/                  All optimized structures (.xyz)

Available commands

sfris run <input> &     Run isomer search

sfris test <input>      Test backend connectivity

sfris config            Show current config

sfris config init       Create default config file

sfris example           List built-in examples

sfris example <name>    Copy example to current directory

Parameters

[CUT]

CutControl = MaxCuts, MinPriority (default: 3, 0.4) — Maximum number of bonds cut simultaneously and minimum bond priority threshold

CutRing = true/false (default: false) — Whether to cut ring bonds

CutMultipleBond = true/false (default: true) — Whether to cut double/triple bonds

[SEARCH]

ConvergenceRounds = PlacementsPerCut, MaxIterations, PlacementAttempts (default: 30, auto, 5) — Number of Fibonacci directions, maximum iterations (auto = calculated from search space), and collision resolution attempts per direction

ScanRotations = N (default: 3) — Deterministic rotations per direction in the two-phase adaptive scan (0 = legacy random mode)

[CLUSTER]

ComboThreshold = ClusterRMSD, ClusterEnergy (default: 0.5, 1.0) — RMSD threshold (Å) and energy threshold (kcal/mol) for duplicate detection

ClusterHeavyOnly = true/false (default: true) — Use only heavy atoms for RMSD calculation

MirrorCheck = true/false (default: false) — Check mirror images during duplicate detection

[FILTER]

EnergyWindow = N (default: 100) — Block 1 energy cutoff relative to reference (kcal/mol)

AdvOptFilter = N (default: 50) — Energy window for Block 2 high-level optimization submission (kcal/mol)

ScanLimit = N (default: 0, disabled) — Early stopping after N consecutive iterations without new structures per cut combination

ScanParallel = N (default: 0, uses NProc) — Number of parallel scan jobs in Stage 1

[ADVOPT]

Include this section header to enable Block 2 (high-level optimization). 

AdvOptMethod = functional/basis (default: B3LYP-D3(BJ)/def2-TZVP)

AdvOptProgram = orca / psi4 / gaussian (default: auto-detect from config)

[NMA]

Include this section header to enable normal-mode analysis 

Notes

Bond connectivity is determined by distance-based criteria using covalent radii, not by electronic structure analysis. 

The energy filtering and deduplication steps are designed to reduce structural redundancy, not to guarantee uniqueness or completeness. 

Users should always carefully check the chemical reasonableness of the final structures. 

To Do List

1. Machine learning for accelerating configurational scanning (Now testing...)

2. Rigorous displacement protocols

3. Automated mapping of isomerization pathways, including transition-state searches and global connectivity networks

4. Kinetic analysis with Wigner, Eckart, and SCT corrections