symvb 2.0.0__tar.gz

symvb-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marat R. Talipov, Punhasa Senanayake, and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

symvb-2.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: symvb
+Version: 2.0.0
+Summary: Symbolic calculations for semi-quantitative Valence Bond Theory
+Home-page: https://github.com/ComputationalChemistry-NMSU/symvb
+Author: Marat Talipov
+Author-email: talipovm@nmsu.edu
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.13
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# symvb
+
+Symbolic valence-bond theory in Python. `symvb` builds Slater
+determinants over user-supplied orbital sets, computes one- and
+two-electron matrix elements via Löwdin's cofactor expansion, and
+returns the resulting Hamiltonian and overlap as `sympy` matrices —
+everything stays symbolic in the bond, overlap, and Coulomb
+parameters until you choose to substitute.
+
+The package targets pedagogical and small-system research use:
+H₂, allyl, benzene, (H₂)ₙ⁺ chains, cyclic polyenes, and similar
+model systems where closed-form analysis is preferable to
+purely numerical FCI.
+
+## Install
+
+```bash
+pip install git+https://github.com/ComputationalChemistry-NMSU/symvb.git
+```
+
+Or clone and run without installing:
+
+```bash
+git clone https://github.com/ComputationalChemistry-NMSU/symvb.git
+cd symvb
+PYTHONPATH=. python3 examples/h2_hubbard_bond.py
+```
+
+Python ≥ 3.8 (tested on 3.8 and 3.11). The symbolic core needs only
+`sympy`; the numeric helpers (`ground_state(subs=...)`, the scan
+patterns) and most examples also use `numpy` and `scipy`. For the
+teaching notebooks add `jupyter` and `matplotlib`.
+
+## Quick start
+
+```python
+from symvb import Molecule, FixedPsi, System
+
+m = Molecule(zero_ii=True, interacting_orbs=['ab'],
+             subst={'h': ('H_ab',), 's': ('S_ab',)},
+             subst_2e={'U': ('1111',)}, max_2e_centers=1)
+cov = FixedPsi('aB'); cov.add_str_det('bA', coef=1)   # Heitler-London singlet
+ion = FixedPsi('aA'); ion.add_str_det('bB', coef=1)   # symmetric ionic
+
+bond = System.from_structures(m, [cov, ion])
+E, c         = bond.ground_state()      # symbolic ground-state energy + vector
+w_cov, w_ion = bond.weights()           # Chirgwin-Coulson weights
+
+benzene = System.ring(6)                # topology fills in every edge + on-site U
+H, S    = benzene.hamiltonian()         # 400x400 sympy matrices, 2e block folded in (~1 min build)
+```
+
+The underlying symbolic matrices stay fully accessible
+(`m.build_matrix(P, op='H')`, `m.o2_matrix(P)`). See
+[docs/recipes.md](docs/recipes.md) for common tasks and
+[docs/api.md](docs/api.md) for the full surface.
+
+## Documentation
+
+- [docs/api.md](docs/api.md) — API reference: modules, signatures, conventions.
+- [docs/recipes.md](docs/recipes.md) — task-oriented cookbook; every snippet is
+  verified by `docs/_recipes_check.py`.
+- [docs/operators_tutorial.md](docs/operators_tutorial.md) — the second-quantized
+  operator algebra, in depth.
+
+[docs/README.md](docs/README.md) is the index.
+
+## Teaching notebooks
+
+`notebooks/` derives valence-bond theory from the ground up with `symvb`; every
+result is *derived*, not quoted. The four main notebooks are companions to the
+manuscript's four model systems:
+
+1. **H₂, the two-center two-electron bond** — covalent/ionic weights versus
+   correlation, the singlet–triplet gap, and charge-shift bonding.
+2. **The allyl anion (3c4e)** — a long-bond Rumer structure as a biradical
+   signature.
+3. **The (H₂)₂⁺ disphenoid (4c3e)** — the Robin–Day Class II/III crossover.
+4. **Benzene** — a covalent-only model inverts the sign of the energy response.
+
+`notebooks/additional/` keeps further topics (the U=J operator identity, the
+Hubbard→Heisenberg mapping, symmetry projection). See
+[notebooks/README.md](notebooks/README.md), and open in Jupyter with:
+
+```bash
+PYTHONPATH=. jupyter notebook notebooks/
+```
+
+## Examples
+
+`examples/` collects 80 stand-alone scripts, most of them cited from
+the manuscript's source-data records. Worked examples cover H₂, H₂⁺,
+allyl (anion / cation / triplet), benzene, (H₂)ₙ⁺ chains for
+$n = 2, 3, 4$, cyclobutadiene dianion, cyclopentadienyl anion, F₂,
+and benzene + O₃ aromaticity loss. Run any script from the repo root
+with `PYTHONPATH=.`:
+
+```bash
+PYTHONPATH=. python3 examples/benzene_heisenberg_mapping.py
+```
+
+A few scripts cache large symbolic matrices under `/tmp` on first run
+(subsequent runs are fast), and the plotting scripts write their PNGs
+into `figures/`.
+
+## Tests
+
+```bash
+PYTHONPATH=. python3 -m pytest symvb -q     # 201 tests
+PYTHONPATH=. python3 docs/_recipes_check.py # every documented recipe, executed
+```
+
+## License
+
+MIT.
+
+## Funding
+
+Research reported in this repository was supported by an
+Institutional Development Award (IDeA) from the National Institute
+of General Medical Sciences of the National Institutes of Health
+under grant number P20GM103451.

symvb-2.0.0/README.md

@@ -0,0 +1,122 @@
+# symvb
+
+Symbolic valence-bond theory in Python. `symvb` builds Slater
+determinants over user-supplied orbital sets, computes one- and
+two-electron matrix elements via Löwdin's cofactor expansion, and
+returns the resulting Hamiltonian and overlap as `sympy` matrices —
+everything stays symbolic in the bond, overlap, and Coulomb
+parameters until you choose to substitute.
+
+The package targets pedagogical and small-system research use:
+H₂, allyl, benzene, (H₂)ₙ⁺ chains, cyclic polyenes, and similar
+model systems where closed-form analysis is preferable to
+purely numerical FCI.
+
+## Install
+
+```bash
+pip install git+https://github.com/ComputationalChemistry-NMSU/symvb.git
+```
+
+Or clone and run without installing:
+
+```bash
+git clone https://github.com/ComputationalChemistry-NMSU/symvb.git
+cd symvb
+PYTHONPATH=. python3 examples/h2_hubbard_bond.py
+```
+
+Python ≥ 3.8 (tested on 3.8 and 3.11). The symbolic core needs only
+`sympy`; the numeric helpers (`ground_state(subs=...)`, the scan
+patterns) and most examples also use `numpy` and `scipy`. For the
+teaching notebooks add `jupyter` and `matplotlib`.
+
+## Quick start
+
+```python
+from symvb import Molecule, FixedPsi, System
+
+m = Molecule(zero_ii=True, interacting_orbs=['ab'],
+             subst={'h': ('H_ab',), 's': ('S_ab',)},
+             subst_2e={'U': ('1111',)}, max_2e_centers=1)
+cov = FixedPsi('aB'); cov.add_str_det('bA', coef=1)   # Heitler-London singlet
+ion = FixedPsi('aA'); ion.add_str_det('bB', coef=1)   # symmetric ionic
+
+bond = System.from_structures(m, [cov, ion])
+E, c         = bond.ground_state()      # symbolic ground-state energy + vector
+w_cov, w_ion = bond.weights()           # Chirgwin-Coulson weights
+
+benzene = System.ring(6)                # topology fills in every edge + on-site U
+H, S    = benzene.hamiltonian()         # 400x400 sympy matrices, 2e block folded in (~1 min build)
+```
+
+The underlying symbolic matrices stay fully accessible
+(`m.build_matrix(P, op='H')`, `m.o2_matrix(P)`). See
+[docs/recipes.md](docs/recipes.md) for common tasks and
+[docs/api.md](docs/api.md) for the full surface.
+
+## Documentation
+
+- [docs/api.md](docs/api.md) — API reference: modules, signatures, conventions.
+- [docs/recipes.md](docs/recipes.md) — task-oriented cookbook; every snippet is
+  verified by `docs/_recipes_check.py`.
+- [docs/operators_tutorial.md](docs/operators_tutorial.md) — the second-quantized
+  operator algebra, in depth.
+
+[docs/README.md](docs/README.md) is the index.
+
+## Teaching notebooks
+
+`notebooks/` derives valence-bond theory from the ground up with `symvb`; every
+result is *derived*, not quoted. The four main notebooks are companions to the
+manuscript's four model systems:
+
+1. **H₂, the two-center two-electron bond** — covalent/ionic weights versus
+   correlation, the singlet–triplet gap, and charge-shift bonding.
+2. **The allyl anion (3c4e)** — a long-bond Rumer structure as a biradical
+   signature.
+3. **The (H₂)₂⁺ disphenoid (4c3e)** — the Robin–Day Class II/III crossover.
+4. **Benzene** — a covalent-only model inverts the sign of the energy response.
+
+`notebooks/additional/` keeps further topics (the U=J operator identity, the
+Hubbard→Heisenberg mapping, symmetry projection). See
+[notebooks/README.md](notebooks/README.md), and open in Jupyter with:
+
+```bash
+PYTHONPATH=. jupyter notebook notebooks/
+```
+
+## Examples
+
+`examples/` collects 80 stand-alone scripts, most of them cited from
+the manuscript's source-data records. Worked examples cover H₂, H₂⁺,
+allyl (anion / cation / triplet), benzene, (H₂)ₙ⁺ chains for
+$n = 2, 3, 4$, cyclobutadiene dianion, cyclopentadienyl anion, F₂,
+and benzene + O₃ aromaticity loss. Run any script from the repo root
+with `PYTHONPATH=.`:
+
+```bash
+PYTHONPATH=. python3 examples/benzene_heisenberg_mapping.py
+```
+
+A few scripts cache large symbolic matrices under `/tmp` on first run
+(subsequent runs are fast), and the plotting scripts write their PNGs
+into `figures/`.
+
+## Tests
+
+```bash
+PYTHONPATH=. python3 -m pytest symvb -q     # 201 tests
+PYTHONPATH=. python3 docs/_recipes_check.py # every documented recipe, executed
+```
+
+## License
+
+MIT.
+
+## Funding
+
+Research reported in this repository was supported by an
+Institutional Development Award (IDeA) from the National Institute
+of General Medical Sciences of the National Institutes of Health
+under grant number P20GM103451.

symvb-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

symvb-2.0.0/setup.py

@@ -0,0 +1,44 @@
+from setuptools import setup
+import os
+
+
+def get_long_description():
+    topdir = os.path.abspath(os.path.join(__file__, '..'))
+    with open(os.path.join(topdir, 'README.md'), 'r') as f:
+        return f.read()
+
+
+def get_version():
+    topdir = os.path.abspath(os.path.join(__file__, '..'))
+    with open(os.path.join(topdir, 'symvb', '__init__.py'), 'r') as f:
+        for line in f.readlines():
+            if line.startswith('__version__'):
+                delim = '"' if '"' in line else "'"
+                return line.split(delim)[1]
+    raise ValueError("Version string not found")
+
+VERSION = get_version()
+
+setup(name='symvb',
+      version=VERSION,
+      description='Symbolic calculations for semi-quantitative Valence Bond Theory',
+      long_description=get_long_description(),
+      long_description_content_type='text/markdown',
+      url='https://github.com/ComputationalChemistry-NMSU/symvb',
+      author='Marat Talipov',
+      author_email='talipovm@nmsu.edu',
+      license='MIT',
+      license_files=['LICENSE'],
+      classifiers=[
+          'Programming Language :: Python :: 3',
+          'License :: OSI Approved :: MIT License',
+          'Intended Audience :: Science/Research',
+          'Topic :: Scientific/Engineering :: Chemistry',
+      ],
+      packages=['symvb'],
+      zip_safe=True,
+      python_requires='>=3.8',
+      # numpy/scipy are imported at module level by molecule, functions,
+      # numerical, symmetry, spin, operators, and mo_projection
+      install_requires=['sympy>=1.13', 'numpy>=1.24', 'scipy>=1.10'],
+      )

symvb-2.0.0/symvb/__init__.py

@@ -0,0 +1,18 @@
+from symvb.slaterdet import SlaterDet
+from symvb.fixed_psi import FixedPsi
+from symvb.molecule import Molecule
+from symvb import symmetry
+from symvb import spin
+from symvb import huckel
+from symvb import mo_projection
+from symvb import operators
+from symvb import system
+from symvb.system import (System, hamiltonian, ground_state,
+                          chirgwin_coulson, structure_vector)
+from symvb.mo_projection import verify_eigenpair, EigenpairResidualError
+
+import logging
+
+logging.basicConfig(format='%(levelname)-8s: %(message)s')
+
+__version__ = "2.0.0"

symvb-2.0.0/symvb/_o2_benchmark.py

@@ -0,0 +1,163 @@
+"""
+Benchmark the two o2_det implementations on a fixed system battery.
+
+Runs each (system, method) combination N_TRIALS times, reports the median
+of wall-time and peak memory, plus the total SymPy-op count of the
+resulting matrix as a proxy for output expression complexity.
+
+Usage:
+    cd vbt-3-repo
+    PYTHONPATH=. python3 -m symvb._o2_benchmark
+"""
+from __future__ import annotations
+
+import gc
+import time
+import tracemalloc
+
+import sympy as sp
+
+from symvb import Molecule
+
+
+# --- Cases ---------------------------------------------------------------
+
+_PPP_2E = {'U': ('1111',), 'J': ('1212',), 'K': ('1122',),
+           'M': ('1112', '1121', '1222')}
+
+
+def _h2(cutoff):
+    return dict(
+        label='H2',
+        Na=1, Nb=1, Norbs=2,
+        kwargs=dict(subst_2e=_PPP_2E,
+                    interacting_orbs=['ab'],
+                    max_2e_centers=cutoff),
+    )
+
+
+def _allyl(cutoff):
+    return dict(
+        label='allyl-3c4e',
+        Na=2, Nb=2, Norbs=3,
+        kwargs=dict(subst_2e=_PPP_2E,
+                    interacting_orbs=['ab', 'bc'],
+                    max_2e_centers=cutoff),
+    )
+
+
+def _benzene_ppp():
+    return dict(
+        label='benzene-PPP',
+        Na=3, Nb=3, Norbs=6,
+        kwargs=dict(
+            zero_ii=True,
+            interacting_orbs=['ab', 'bc', 'cd', 'de', 'ef', 'af'],
+            subst={'h': ('H_ab', 'H_bc', 'H_cd', 'H_de', 'H_ef', 'H_af'),
+                   's': ('S_ab', 'S_bc', 'S_cd', 'S_de', 'S_ef', 'S_af')},
+            subst_2e=_PPP_2E,
+            max_2e_centers=2,
+        ),
+    )
+
+
+CASES = [
+    (_h2(cutoff=1), 5),
+    (_h2(cutoff=2), 5),
+    (_allyl(cutoff=1), 5),
+    (_allyl(cutoff=2), 5),
+    (_allyl(cutoff=3), 3),
+    (_allyl(cutoff=4), 3),
+    (_benzene_ppp(), 1),  # 1 trial; if blocked is fast we can rerun with more
+]
+
+
+# --- Bench runner --------------------------------------------------------
+
+def _build_matrix_o2(method, case):
+    m = Molecule(o2_method=method, **case['kwargs'])
+    m.generate_basis(case['Na'], case['Nb'], case['Norbs'])
+    return m.o2_matrix(m.basis)
+
+
+def _count_ops(matrix):
+    return sum(int(matrix[i, j].count_ops())
+               for i in range(matrix.rows) for j in range(matrix.cols))
+
+
+def _trial(method, case):
+    gc.collect()
+    tracemalloc.start()
+    t0 = time.perf_counter()
+    H2 = _build_matrix_o2(method, case)
+    wall = time.perf_counter() - t0
+    _, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    ops = _count_ops(H2)
+    n = H2.rows
+    return dict(wall=wall, peak_mb=peak / (1024 * 1024), ops=ops, dim=n)
+
+
+def _median(xs):
+    xs = sorted(xs)
+    n = len(xs)
+    if n == 0:
+        return float('nan')
+    if n % 2 == 1:
+        return xs[n // 2]
+    return 0.5 * (xs[n // 2 - 1] + xs[n // 2])
+
+
+def benchmark():
+    print('=' * 78)
+    print('Two-electron matrix benchmark: direct vs blocked')
+    print('=' * 78)
+    print()
+    header = ('| %-15s | %-7s | %-7s | dim   | wall (s)   | peak (MB)  '
+              '| ops      | speedup |')
+    sep = ('|-----------------|---------|---------|-------'
+           '|------------|------------|----------|---------|')
+    print(header % ('system', 'cutoff', 'method'))
+    print(sep)
+    for case, n_trials in CASES:
+        cutoff = case['kwargs'].get('max_2e_centers', 4)
+        results = {}
+        for method in ('direct', 'blocked'):
+            print('  ... %s cutoff=%d %s (n=%d)'
+                  % (case['label'], cutoff, method, n_trials), flush=True)
+            trials = []
+            for ti in range(n_trials):
+                t = _trial(method, case)
+                trials.append(t)
+                print('      trial %d: wall=%.3fs peak=%.1fMB'
+                      % (ti, t['wall'], t['peak_mb']), flush=True)
+            results[method] = dict(
+                wall=_median([t['wall'] for t in trials]),
+                peak_mb=_median([t['peak_mb'] for t in trials]),
+                ops=trials[0]['ops'],
+                dim=trials[0]['dim'],
+            )
+        # Print rows; speedup column shown on the blocked row only.
+        for method in ('direct', 'blocked'):
+            r = results[method]
+            speedup = ''
+            if method == 'blocked' and results['direct']['wall'] > 0:
+                speedup = '%.2fx' % (results['direct']['wall'] / r['wall'])
+            print('| %-15s | %-7d | %-7s | %-5d | %-10.3f | %-10.2f '
+                  '| %-8d | %-7s |'
+                  % (case['label'], cutoff, method, r['dim'],
+                     r['wall'], r['peak_mb'], r['ops'], speedup))
+        # Sanity: ops should agree (modulo chemist-symmetry symbol naming).
+        ops_diff = results['direct']['ops'] - results['blocked']['ops']
+        if ops_diff != 0:
+            print('|   ^ ops differ by %+d (chemist-symbol naming, not '
+                  'a correctness issue)' % ops_diff)
+    print()
+    print('Notes:')
+    print(' - wall and peak_mb are medians across N_TRIALS runs.')
+    print(' - ops = sum of sympy.count_ops() over all matrix entries.')
+    print(' - speedup > 1 means blocked is faster.')
+
+
+if __name__ == '__main__':
+    benchmark()