SigmaScope

SMILES in, σ-profile out. SigmaScope looks up a molecule in the CHAOS quantum-chemical database and returns its COSMO-SAC-dsp σ-profile, plus the polar and hydrogen-bond donor/acceptor surface areas derived from it.

CHAOS ships as a single 4 GB ZIP. SigmaScope never downloads it. It reads the ZIP64 central directory once over an HTTP range request, then pulls individual molecule records on demand — about 76 KB per compound, cached locally, so a lookup costs under a megabyte.

from sigmascope import Client

prof = Client().profile("CCO")            # ethanol
prof.a_total()                            # area profile A(σ) in Ų, sums to the cavity area
prof.a_polar()                            # polar area  [Ų]
prof.a_minus(), prof.a_plus()             # H-bond donor / acceptor area [Ų]

SigmaScope retrieves and analyses profiles. It does not compute activity coefficients and is not a COSMO-SAC implementation.

---

Install

rdkit is the fragile dependency — the PyPI wheel is not available on every platform — so conda-forge is the tested path:

conda env create -f environment.yml
conda activate sigmascope
pip install -e .

Windows gotcha. Always use the activated environment (or conda run -n sigmascope ...). Calling the environment's python.exe by absolute path without activating leaves envs\sigmascope\Library\bin off the PATH, and matplotlib then dies at render time with a native 0xC06D007F delay-load error. Selecting the interpreter in VS Code / VSCodium handles this for you.

Quickstart

Build the identifier index once (fetches the 2 MB SMILES dictionary, then runs RDKit over 53,091 molecules — about a minute):

sigmascope index

Then:

sigmascope get CCO                                  # print header + 51-point table
sigmascope get O CCO CC(=O)C -o out/ --json         # small batch, exported
sigmascope list C2H6O                               # disambiguate a formula
sigmascope plot O CCO Cc1ccccc1 -o overlay.png      # overlay

Or the desktop GUI — paste SMILES one per line, retrieve, read the table or the embedded figure, export CSV/JSON/PNG:

python -m sigmascope.gui

Selecting a molecule

The Python API and CLI accept whichever identifier is convenient:

Identifier	Example	Notes
SMILES	OCC, CCO, C(C)O	RDKit-canonicalised first, so all three give ethanol
InChIKey	LFQSCWFLJHTTHZ-UHFFFAOYSA-N	robust to SMILES-writing differences
CHAOS id	27202	direct lookup
formula	C2H6O	may match several isomers — you get the list, never a silent pick
name	ethanol	only names present in data/aliases.csv (editable, seeded with five)

A query that resolves to nothing says so and suggests same-formula candidates. It never substitutes a different molecule.

The GUI is SMILES-only — one per line, capped at 20 per run. Names, ids, InChIKeys and formulae are rejected there, and a line that is not valid SMILES is flagged before you retrieve. The cap comes from Zenodo's rate limit (133 requests/minute); 20 uses about 15 % of it. Repeated identical lines are dropped and the count says so, e.g. 13 / 20 compounds — 2 duplicate lines ignored.

SMILES is case-sensitive: C1CCCCC1 is cyclohexane, c1ccccc1 is benzene. Input is compared exactly and never case-folded.

What you get

Every profile is validated before it is returned (51 bins, non-negative, class fractions summing to 1, cavity area consistent). A failure raises rather than returning a questionable number.

σ grid	51 points, −0.025 … +0.025 e/Ų, step 0.001
partials	NHB / OH / OT, each normalised (Σ = 1, or 0 if absent)
p_total	normalised total, Σ = 1
A_total	area profile in Ų, Σ = cavity area
A_polar	Σ A(σ) over |σ| ≥ σ_hb
A_minus / A_plus	H-bond donor / acceptor area
provenance	CHAOS id, version, DOI, license, level of theory

CSV export states its convention in the header and never writes a bare, ambiguous y-axis. Columns:

sigma_e_per_A2, p_total, p_NHB, p_OH, p_OT,
A_total_A2, A_NHB_A2, A_OH_A2, A_OT_A2,
A_polar_A2, A_polar_over_A_total,        # with --polar / the GUI checkbox
A_minus_A2, A_plus_A2                    # with the H-bond split

Each A_polar* / A_minus / A_plus column sums to the molecule-level scalar, which is also written in the header.

Polar and hydrogen-bond areas

σ ≤ −σ_hb  →  DONOR     (acidic H)    →  A⁻
σ ≥ +σ_hb  →  ACCEPTOR  (lone pairs)  →  A⁺
A_polar = A⁻ + A⁺

σ_hb = 0.0084 e/Ų is the Lin & Sandler cutoff — an exact model constant, not a rounded figure; it appears verbatim as sigma_hb [e/A^2]: 0.0084 in the NIST reference implementation of COSMO-SAC-dsp. It is editable in the GUI.

The grid cannot resolve it exactly. Bins are 0.001 wide, so 0.0084 falls inside a bin: |σ| = 0.008 is excluded, |σ| ≥ 0.009 included, making the effective cutoff 0.009. SigmaScope reports that per compound and writes it into the CSV header. Any threshold from 0.0081 to 0.0090 gives the same result.

Effective site counts are n = A / 7.25 Ų, the standard COSMO-SAC effective segment area. This measures how much donor/acceptor surface a molecule presents — it is continuous, lands near chemical intuition (water gives ≈2.0 donor sites for its two O–H bonds), but is not an integer count of atoms.

Sanity check across chemistry, with the default cutoff:

	water	acetic acid	ethanol	CHF₃	CHCl₃	CH₃CF₃	benzene
A_polar / A_total	0.651	0.262	0.202	0.119	0.063	0.0004	0.000

CHF₃ against CH₃CF₃ is the informative pair: swapping fluoroform's acidic C–H for a methyl removes essentially all polar surface, as it should.

A unit trap worth knowing about

CavArea and CavVolume in a CHAOS record are in atomic units (bohr², bohr³), not Ų/ų, despite the names. The Ų cavity area is Norm_Sigma_total, and Sigma_total is the area profile in Ų.

Reading CavArea as Ų inflates every area by 1/0.280028 ≈ 3.571×. It is easy to miss because a Σ A(σ) == CavArea self-check passes either way — both sides carry the same wrong unit. Published cavity data settles it: water is 42.90 Ų (literature ~43), not 153.20.

SigmaScope exposes the converted Ų/ų values as cav_area / cav_volume and keeps the raw fields as cav_area_bohr2 / cav_volume_bohr3. Pinned by tests/test_profile.py::test_cavity_units_are_angstrom. Full evidence in docs/chaos-data-format.md §4.

Known limitations

• Retrieval, not computation. Profiles are the ones CHAOS shipped. Nothing is recomputed; see docs/extending.md for what a reimplementation from the raw segments would involve.
• The index needs one full pass. sigmascope index runs RDKit over all 53,091 dictionary keys (~1 min). Cached afterwards.
• Zenodo rate limit — 133 requests/minute. Large sweeps need pacing; the cache means repeats are free.
• A few records are internally inconsistent. For some molecules CavArea × 0.280028 disagrees with Σ Sigma_total by ~1.5 % (pyridine, id 53002). Norm_Sigma_total is treated as authoritative and the cross-check is deliberately loose.
• The 9th SegmentList column is unidentified. It is not the averaged σ, and binning it does not reproduce the shipped profile.
• not_converged is surfaced but not treated as a hard failure — check it.

Data provenance and citation

The CHAOS data is CC-BY-4.0, which requires attribution when you use or redistribute profiles obtained through this tool.

CHAOS database

Gond, D.; Arweiler, J.; Specht, T.; Hasse, H.; Jirasek, F. CHAOS — A Large-scale Database for Sigma-Profiles and Other Molecular Descriptors. Zenodo, 2026. DOI: 10.5281/zenodo.17691924 (version used here: 10.5281/zenodo.18701299). Licensed CC-BY-4.0. Cite also the associated journal article — see the Zenodo record.

COSMO-SAC-dsp protocol

Bell, I. H.; Mickoleit, E.; Hsieh, C.-M.; Lin, S.-T.; Vrabec, J.; Breitkopf, C.; Jäger, A. A Benchmark Open-Source Implementation of COSMO-SAC. J. Chem. Theory Comput. 2020, 16 (4), 2635–2646. DOI: 10.1021/acs.jctc.9b01016

SigmaScope — see CITATION.cff.

Do not mix levels of theory

CHAOS profiles are ωB97X-D/def2-TZVP with C-PCM. Classic COSMO-SAC parameter sets were fitted to DMol³ BP/DNP profiles. Profiles and parameters from different levels of theory are not interchangeable — using CHAOS profiles with parameters fitted elsewhere gives wrong activity coefficients.

Layout

src/sigmascope/
    constants.py   σ grid, unit factors, σ_hb, provenance
    _chem.py       RDKit helpers (canonical SMILES, InChIKey, formula)
    index.py       build/load the identifier index; resolve queries
    fetch.py       selective retrieval (cache → local zip → HTTP range GET)
    profile.py     SigmaProfile: validation, p(σ)/A(σ), polar & H-bond areas
    export.py      CSV/TSV + JSON writers
    plot.py        plain σ-profile plotting
    cli.py         the sigmascope command
    gui.py         Tkinter desktop app
    ext/           extension-point stubs (documented, not implemented)
docs/              chaos-data-format.md, extending.md
tests/             offline suite + committed fixture
data/              runtime cache (git-ignored) + aliases.csv

Development

pip install -e ".[test]"
pytest

The suite is fully offline — it runs against the committed tests/fixtures/mini_chaos.zip (real records, trimmed) and never calls Zenodo, so it works without network access and CI needs no credentials.

Author

Cleiton S. Beraldo — cleitonberaldo@alumni.usp.br · @311cleiton

Acknowledgment

This project was developed with the assistance of Claude Code, Anthropic's CLI for Claude. The data-format findings documented here — the cavity-unit correction, the σ sign convention, the σ_hb discretisation, the mixed units in SegmentList — were verified against real CHAOS records rather than assumed, and each is pinned by the test suite.