sfris 1.0.0

Systematic Fragmentation-Recombination Isomer Search: automated constitutional isomer generation

SFRIS

Systematic Fragmentation-Recombination Isomer Search

SFRIS is a computational chemistry tool for automated constitutional isomer generation. It systematically dissects molecular bonds according to priority rules, places fragments in 3D space via Fibonacci sphere sampling, and refines candidates through a multi-level optimization pipeline.

• Author: Dapeng Zhang (ORCID)
• License: MIT
• Homepage: https://halsten.pcmq.net

Installation

pip install sfris

External dependencies

SFRIS requires at least one of the following quantum chemistry programs (not included):

Program	Role	Notes
xTB	Block 1 (semi-empirical screening)	Required
ORCA	Block 2 (DFT refinement)	Optional
Psi4	Block 2 (DFT refinement)	Alternative to ORCA
Gaussian	Block 2 (DFT refinement)	Alternative to ORCA

Quick start

1. Configure software paths (once per machine)

sfris config init

Edit ~/.config/sfris/config with your paths:

[settings]
XtbPath = /path/to/xtb
OrcaPath = /path/to/orca
NProc = 8
ScratchDir = /tmp/sfris_scratch

2. Get an example and run

sfris example CH4O
sfris run CH4O.inp &

Results are written to the ISOMER/ directory as individual .xyz files, sorted by energy. Progress is logged in SFRIS.run.

Usage

sfris run <input_file>      # Run full search (background-safe)
sfris test <input_file>     # Test backend connectivity
sfris <input_file>          # Initialize and validate input
sfris config                # Show current config
sfris config init           # Create default config file
sfris example               # List example molecules
sfris example <name>        # Copy example to current directory

Input file format

# Comment
0 1
C   0.000   0.000   0.000
O   1.200   0.000   0.000
H  -0.540   0.940   0.000
H  -0.540  -0.940   0.000
Parameters
[CUT]
CutControl = 3, 0.4
[SEARCH]
ConvergenceRounds = 30, auto, auto
[CLUSTER]
MirrorCheck = true
[FILTER]
ScanLimit = 150
AdvOptFilter = 50
[ADVOPT]
[NMA]
[]

The [] end marker is required. Machine-specific settings (paths, nproc) are read from the config file and do not need to be specified in the input.

Block control

• Block 1 only (xTB screening): omit [ADVOPT] from the input file.
• Block 1 + Block 2 (DFT refinement): add [ADVOPT]. The DFT program is auto-detected from config paths, or set explicitly with AdvOptProgram = orca.
• Frequency analysis: add [NMA] (requires [ADVOPT]).

Method specification

Methods are written as Functional-Dispersion/Basis:

AdvOptMethod = B3LYP-D3(BJ)/def2-TZVP
AdvOptMethod = PBE0-D3BJ/6-311+G(d,p)
AdvOptMethod = wB97X-D3/cc-pVTZ
AdvOptMethod = M06-2X/aug-cc-pVDZ

SFRIS automatically translates method strings into the correct syntax for each backend (ORCA, Psi4, Gaussian). Pople, Dunning, and Karlsruhe basis sets are all supported.

How it works

SFRIS operates in two blocks:

• Block 1: Molecular bonds are systematically cut according to priority rules. Fragments are recombined by placement on a Fibonacci sphere, then screened and optimized at the GFN2-xTB level with triple-gate deduplication (energy, RMSD, graph isomorphism).
• Block 2 (optional): Unique isomers from Block 1 are re-optimized at the DFT level with a second round of deduplication.

Stopping and resuming

SFRIS supports graceful interruption. To stop a running calculation:

touch CH4O.STOP

SFRIS will save a checkpoint and exit at the next safe point. To resume:

sfris run CH4O.inp &

The calculation continues from where it stopped.

Supported elements

C, H, N, O, S, P, F, Cl, Br

Citation

If you use SFRIS in your research, please cite:

Zhang, D. (2026). SFRIS: Systematic Fragmentation and Recombination for Automated Constitutional Isomer Generation. doi: forthcoming

See also CITATION.cff for machine-readable citation metadata.