Skip to main content

ChemiGraph logo

ChemiGraph

A Python Library for Chemical Graph Theory

ChemiGraph turns a molecular structure into quantum-chemical insight using only graph theory and linear algebra. It is a fully automated implementation of the Valency Interaction Formula (VIF) theory — formulated by Oktay Sinanoğlu (Theoret. Chim. Acta 1985, 68, 251) — and its application to mass spectrometry by Berkay Sütay (JOTCSA 2017, 4(1), 179).

Give it nothing but a structure (a SMILES string or a PubChem name) and it will:

  • build the VIF graph of the molecule,
  • compute the Level Pattern Indices (LPI) = the exact count of bonding, nonbonding and antibonding molecular orbitals,
  • locate the soft bonds (the weakest linkages), and
  • predict the principal electron-impact (EI) mass-spectral fragmentsa priori, in milliseconds, without any large-scale quantum-chemical computation.

Theoretical background

1. The molecule becomes a graph. Each atom is drawn as a set of vertices equal to the size of its valence shell — 1 for H/He, 4 (s + 3p) for the second- and third-row main-group elements, 9 for transition metals. The vertices of one atom form an intra-atomic clique (the hybrid-orbital interactions), and each chemical bond is an edge joining vertices of neighbouring atoms.

2. The graph is the Hamiltonian. This picture is exactly the matrix representation — the adjacency matrix — of the one-electron molecular Hamiltonian in a non-orthonormal valence-orbital basis. Nothing is approximated away; the graph encodes the same connectivity the operator does.

3. Reduction = congruence = invariant signature. Sinanoğlu showed that the pictorial reduction rules of VIF are congruence transformations (A → SᵀAS) of this matrix under the general linear group. By Sylvester's law of inertia (1852), a congruence transformation cannot change the signature — the number of positive, zero and negative eigenvalues. That invariant is the LPI:

LPI = (n+, n0, n-)
      n+  = # positive eigenvalues = bonding molecular orbitals
      n0  = # zero eigenvalues     = nonbonding molecular orbitals
      n-  = # negative eigenvalues = antibonding molecular orbitals

So the electronic level pattern of a molecule can be read off its structural formula alone — no basis-set SCF cycle required.

4. Soft bonds and mass spectra. Sütay's insight (2017) is that the interactions which cancel during reduction — the soft bonds — are the chemically weakest linkages, and are precisely the bonds that break first under 70 eV electron impact. Each soft-bond cleavage is a fragment peak in the mass spectrum.

What ChemiGraph adds

It reduces Sinanoğlu's hand-drawn calculus directly to numerical linear algebra:

LPI(G) = signature of the adjacency matrix of G,  via numpy.linalg.eigvalsh   (O(n³))

Soft-bond detection is a rank-2 perturbation test: if deleting bond (i, j) leaves the LPI unchanged, that bond would already have vanished during reduction — so it is soft. A chemically motivated α-cleavage rule suppresses unphysical fragments (e.g. a bare carbonyl oxygen would never leave as atomic O), and every m/z is reported on the nominal-mass (most-abundant-isotope) scale, the mass-spectrometric convention.

The implementation reproduces the reference LPI values of Sinanoğlu (1985) and the mass-spectral predictions of Sütay (2017) — including the chlorine- substituted cyclohexanone-oxime of the 2017 paper, for which it returns the experimental peaks at m/z = 35 (Cl), 17 (OH) and 218 (M − OH) exactly.


Worked example — nitrobenzene

chemigraph nitrobenzene

Nitrobenzene VIF graph    Nitrobenzene predicted MS

Left — the VIF graph. Every atom is a coloured clique of valence-orbital vertices; solid black edges are ordinary bonds; red dashed edges are soft bonds. The single soft bond linking the benzene ring to the nitro group is the C–N bond — LPI = {18, 0, 23}.

Right — the predicted mass spectrum. Because the C–N bond is soft, the nitro group is lost, giving the phenyl cation C₆H₅⁺ at m/z = 77 — the dominant fragment observed experimentally — alongside the molecular ion M⁺ at 123. This matches Figure 6 of Sütay (2017).

Bar heights are schematic: VIF predicts which fragments form, not their intensities.


Installation

ChemiGraph is distributed as a pre-compiled package — one pip command installs it and its five scientific dependencies (numpy, networkx, matplotlib, rdkit, mendeleev). Python 3.9+ is required.

pip install chemigraph

pip automatically downloads the pre-built binary matching your operating system (Linux, Windows, macOS) and Python version. Alternatively, grab the wheel for your platform from the Releases page and install it directly:

pip install chemigraph-1.0.0-<your-platform>.whl

Windows users: install Python from https://www.python.org/downloads/ (tick “Add Python to PATH” during setup), then open the Command Prompt (Win + Rcmd → Enter) and run pip install chemigraph. A virtual environment (python -m venv venv && source venv/bin/activate) is recommended on every platform.


Usage

From the terminal

After installation a chemigraph command is available everywhere:

chemigraph aspirin                 # a molecule name → fetched from PubChem
chemigraph "Clc1ccccc1"            # a raw SMILES string
chemigraph caffeine nitrobenzene   # several molecules in one run
chemigraph                         # no argument → the substituted-halogen demo

Each molecule prints its LPI and predicted fragment list, and opens two windows: the VIF graph and the predicted mass spectrum.

As a Python library

import chemigraph as cg

# Full analysis from a SMILES string
result = cg.VIF("Clc1ccccc1")           # chlorobenzene
lpi = result["lpi"]
print(lpi["n+"], lpi["n0"], lpi["n-"])  # 15 0 18   (bonding / nonbonding / antibonding)
print(result["mol_mass"])               # 112       (nominal M+)

# Fetch a molecule by name from PubChem
cg.VIF_from_pubchem("nitrobenzene")

# Silent analysis (no plots), inspect the fragments
r = cg.VIF("CC(=O)Oc1ccccc1C(=O)O", draw=False, show_spectrum=False, verbose=False)
for f in r["fragments"]:
    if f["split"]:
        print(f["bond"], "->", [(x[0], x[2]) for x in f["fragments"]])

Interpreting the output

Field Meaning
lpi {n+, n0, n-} — counts of bonding / nonbonding / antibonding MOs
mol_mass nominal mass of the molecular ion M⁺ (m/z)
soft_bonds the weak interactions detected by the perturbation test
fragments predicted EI fragments; each split gives two (formula, m/z) pairs

References

  1. O. Sinanoğlu, Theoret. Chim. Acta 1985, 68, 251.
  2. O. Sinanoğlu, Chem. Phys. Lett. 1984, 103, 315.
  3. B. Sütay, J. Turk. Chem. Soc. A 2017, 4(1), 179.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

chemigraph-1.0.2-cp313-cp313-win_amd64.whl (198.1 kB view details)

Uploaded CPython 3.13Windows x86-64

chemigraph-1.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

chemigraph-1.0.2-cp313-cp313-macosx_10_13_universal2.whl (494.6 kB view details)

Uploaded CPython 3.13macOS 10.13+ universal2 (ARM64, x86-64)

chemigraph-1.0.2-cp312-cp312-win_amd64.whl (196.6 kB view details)

Uploaded CPython 3.12Windows x86-64

chemigraph-1.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

chemigraph-1.0.2-cp312-cp312-macosx_10_13_universal2.whl (495.7 kB view details)

Uploaded CPython 3.12macOS 10.13+ universal2 (ARM64, x86-64)

chemigraph-1.0.2-cp311-cp311-win_amd64.whl (201.9 kB view details)

Uploaded CPython 3.11Windows x86-64

chemigraph-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

chemigraph-1.0.2-cp311-cp311-macosx_10_9_universal2.whl (496.3 kB view details)

Uploaded CPython 3.11macOS 10.9+ universal2 (ARM64, x86-64)

chemigraph-1.0.2-cp310-cp310-win_amd64.whl (201.6 kB view details)

Uploaded CPython 3.10Windows x86-64

chemigraph-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

chemigraph-1.0.2-cp310-cp310-macosx_10_9_universal2.whl (501.4 kB view details)

Uploaded CPython 3.10macOS 10.9+ universal2 (ARM64, x86-64)

chemigraph-1.0.2-cp39-cp39-win_amd64.whl (202.1 kB view details)

Uploaded CPython 3.9Windows x86-64

chemigraph-1.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

chemigraph-1.0.2-cp39-cp39-macosx_10_9_universal2.whl (505.8 kB view details)

Uploaded CPython 3.9macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file chemigraph-1.0.2-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: chemigraph-1.0.2-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 198.1 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for chemigraph-1.0.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ed836bdac9a13505c684295cd12300fdb288f80b052b58aed72188cd284b190a
MD5 862c6240ed9572188795f0938b32127d
BLAKE2b-256 2f5f911eece21edffe17d83bc6e95494ccd01196994f34ac7ecfe86eff2b47d1

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp313-cp313-win_amd64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cb615bbf3c9943dae5b21a0761f882523a64ce9ff96464a650b72ea1e593f8b6
MD5 f20b7e57935116606b1d9218e234e03d
BLAKE2b-256 3aa20e79bb9e6fbccfd75711779c6c952066841296293cb69fc3ff6e8ecca2c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp313-cp313-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 22a208fc194695baca500e29130139f8150d3d4baf153e611c46e631e0abd726
MD5 8fa8a0ce1238af0076e1e8923bd14da8
BLAKE2b-256 68060f2ae86eeda42eb8dd74a9a50099db8539c2209729f6e09f3c16240ec51a

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp313-cp313-macosx_10_13_universal2.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: chemigraph-1.0.2-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 196.6 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for chemigraph-1.0.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 784cee6def268ea0aba22818cff5b55fb97d67290cf25c089a8a1b2a3ce5d47e
MD5 94a6cf7d94d45c4b29649fd8058f0213
BLAKE2b-256 2c199a860050e29921f4509b909a4b3fc68d0dff4396bccf63ef91dbf5cf2223

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp312-cp312-win_amd64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ed309b9e701edf17d1bc5b70a0ef42f19bae7df1dc47a57d8574e29fd3823df6
MD5 090cda9dc96bf90e0867c6cfd010d457
BLAKE2b-256 332607fc35bd4b537ef061d5958c53c091d503adf468a35fcae7951eea56c98b

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 96924654e5f01ba2c5da89cd2397d6b022f99111d6ede67411cec8e71d0c9477
MD5 5759aae3977088b838f3573a6b1e7ead
BLAKE2b-256 4bb5d86909ef09aa5c566f7fd580d06e81af2a52387fc32efce33a2e68335fa9

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp312-cp312-macosx_10_13_universal2.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: chemigraph-1.0.2-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 201.9 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for chemigraph-1.0.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 45f2e021370e50a1e032afb99f982caa9b11b70e1662c8909e215e948b6e3a76
MD5 0dbe8a3a45aa22d13932b82ca91d1989
BLAKE2b-256 a72febb4a87912ff71e2fbd3bbab84c9e48af9e964ae3da8a9744d7cd88d68e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp311-cp311-win_amd64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 076549377a2ebb1a8a431a949cb6d6c4d21de7b891cb9f2f8e08ad263a5543e3
MD5 f46a46e093b578e8aaece17198098b83
BLAKE2b-256 72e892498614d2994dbb74b87549c555c50f7999b7310087afc3beaf220900ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 00cb0516129ec4db391b3633bee16b7926627a7b7cb228695cf07ba1e6e376fb
MD5 96a532c62fa4eae21b6bcf8925daf4a9
BLAKE2b-256 92cc2c62a00720fa60c1a37d97236a0d18620bc91bdef48e9b9f1525acf65693

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp311-cp311-macosx_10_9_universal2.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: chemigraph-1.0.2-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 201.6 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for chemigraph-1.0.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 4654ec906c75f4d1e5172fee411ccc8473c0e0d0b160906c9586609b11fdf162
MD5 10db99b37d6f5b0aa2ba0fd87f92856b
BLAKE2b-256 7758525939e2d1a36aa5fbcbe595728935d0d73f9f0fb45dda7671a21d54ca8d

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp310-cp310-win_amd64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0d6a689e8f20b181529e60bbe0e1a08a7506959038c09364d4a461bfed64ed9e
MD5 70f3f47e7518c55fc4584f0a82fe50fb
BLAKE2b-256 1c950db1d53d173595a2b05fd6396c2efa4c5884052ce37ae564a9ce647ceb13

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp310-cp310-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 42b3a5f6ed52c07db96f94569a1461d06718796e6e03336c1eee549203a63bcb
MD5 285289707332ad10a02d010e06cab8bb
BLAKE2b-256 ddbeb81d2b13b8fbbc1a60aa24ff7e75484b6017fe16b66d4e0edd59395ea5e5

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp310-cp310-macosx_10_9_universal2.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: chemigraph-1.0.2-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 202.1 kB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for chemigraph-1.0.2-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 8eef3a3d36d9976c774082f5f5f14d596045578f48b135cd4c3ea7ddac49446a
MD5 622af931d85be83ded3032554ccc1bc0
BLAKE2b-256 fd5ef6ad18503b2bc9619d62afcf7d808a99d18e7882d434d199bce1b9621ea8

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp39-cp39-win_amd64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1a76d5d6e0eb1f80eddc2d62f66c886175b7fdf517b97655fe9e4832d17c0849
MD5 670d1abac36c686ffec4731d96a7bd95
BLAKE2b-256 faab8f59c087d4cdcd5bcd257310ad298d5d6ef129066ff4f45b47215081fc04

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemigraph-1.0.2-cp39-cp39-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for chemigraph-1.0.2-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 82e71027772565aef559f1219dd37bbb1b0c25a70011a1b0f3bacb898c4fb20f
MD5 1203f1a50c4ec1c31b61a0589a5eb39a
BLAKE2b-256 f2f910a012c7b9837a2b75d32a61f521b01bb4baf6e075e88c55b6262b514adb

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemigraph-1.0.2-cp39-cp39-macosx_10_9_universal2.whl:

Publisher: wheels.yml on SinanGokmen/chemigraph-src

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.2 This release

15 files

1.0.1

12 files

1.0.0

12 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page