qcmr.vbcas 0.5.1__tar.gz

qcmr_vbcas-0.5.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: qcmr.vbcas
+Version: 0.5.1
+Summary: VB-analysis of CAS-CI expansion
+Author-Email: Mariusz Radon <mariusz.radon@uj.edu.pl>
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: roman>=4.2
+Requires-Dist: wrapfile>=0.1
+Requires-Dist: pandas>=1.5.2
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: matplotlib>=3.7.4
+Description-Content-Type: text/markdown
+
+# qcmr.vbcas
+
+VB-CAS = Valence Bond (VB) analysis of CASSCF wave function
+in the basis of (partially) localized orbitals.
+
+The tool supports VB-CAS analysis to calculate cumulative
+percentage contributions of various resonance structures
+based on [Open]Molcas RASSCF output files. It can also 
+produce simple piechart out of the results.
+
+For description and examples of VB-CAS analyses,
+see the following papers (DOIs):
+10.1016/j.jcat.2020.07.018,
+10.3390/molecules26061511,
+10.1039/c5cp07452e,
+10.1021/jp910220r
+

qcmr_vbcas-0.5.1/README.md

@@ -0,0 +1,17 @@
+# qcmr.vbcas
+
+VB-CAS = Valence Bond (VB) analysis of CASSCF wave function
+in the basis of (partially) localized orbitals.
+
+The tool supports VB-CAS analysis to calculate cumulative
+percentage contributions of various resonance structures
+based on [Open]Molcas RASSCF output files. It can also 
+produce simple piechart out of the results.
+
+For description and examples of VB-CAS analyses,
+see the following papers (DOIs):
+10.1016/j.jcat.2020.07.018,
+10.3390/molecules26061511,
+10.1039/c5cp07452e,
+10.1021/jp910220r
+

qcmr_vbcas-0.5.1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "qcmr.vbcas"
+description = "VB-analysis of CAS-CI expansion"
+authors = [
+    { name = "Mariusz Radon", email = "mariusz.radon@uj.edu.pl" },
+]
+dynamic = []
+dependencies = [
+    "roman>=4.2",
+    "wrapfile>=0.1",
+    "pandas>=1.5.2",
+    "numpy>=1.23.5",
+    "matplotlib>=3.7.4",
+]
+requires-python = ">=3.8"
+readme = "README.md"
+version = "0.5.1"
+
+[project.license]
+text = "MIT"
+
+[project.scripts]
+vbcas = "qcmr.vbcas.cli:main"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.build]
+includes = [
+    "src/qcmr/vbcas",
+]
+
+[dependency-groups]
+dev = [
+    "ipython>=8.12.3",
+    "pytest>=8.3.5",
+]

qcmr_vbcas-0.5.1/src/qcmr/vbcas/__init__.py

@@ -0,0 +1,11 @@
+from .vbcas import readci, analyze, piechart
+__all__=["readci", "analyze", "piechart"]
+
+from importlib.metadata import version, PackageNotFoundError
+try:
+    __version__ = version("qcmr.vbcas")
+except PackageNotFoundError:
+    try:
+        __version__ = version("qcmr-vbcas")
+    except PackageNotFoundError:
+        __version__ = "unknown"

qcmr_vbcas-0.5.1/src/qcmr/vbcas/cli.py

@@ -0,0 +1,114 @@
+import argparse
+import sys
+import matplotlib.pyplot as plt
+
+from qcmr.vbcas import readci, analyze, piechart, __version__
+
+def main():
+    ap = argparse.ArgumentParser('vbcas')
+    ap.add_argument(
+        'molcas_output', type=str,
+        help='Molcas (RASSCF) output with CI expansion to analyse'
+    )
+    ap.add_argument(
+        'k', metavar='K', type=int,
+        help="""The number of orbitals to count electrons in the CSF
+        (reading a CSF string from left to right).
+        The number of electrons/charge and spin (if applicable)
+        will be calculated based on orbitals 1 to K (default)
+        or (with --after) orbitals starting from K+1."""
+    )
+    ap.add_argument(
+        '--after', '-a', action='store_true',
+        help="""Changes how argument K is interpreted. See above"""
+    )
+    ap.add_argument(
+        '--nelec', '-n', metavar='N', type=int,
+        help="""The number of electrons which corresponds to the
+        oxidation state zero. If this is provided, the CSFs will
+        be classified using charge rather than electron count
+        (optional, the default is to classify
+        CSF by the electron count)."""
+    )
+    ap.add_argument(
+        '--spin', '-s', action='store_true',
+        help="""Classify CSFs not only by the number of electrons/charge,
+        but also by the spin stemming from electrons in orbitals 1 to K
+        (optional, the default is to ignore the spin)."""
+    )
+    ap.add_argument(
+        '--thresh', '-t', type=float,
+        help="threshold for printing individual CSFs"
+    )
+    ap.add_argument(
+        '--roman', action='store_true',
+        help='''Format oxidation state using Roman numbers.
+        Only applicable if --nelec was used.'''
+    )
+    ap.add_argument(
+        '--add-bar', action='store_true',
+        help='''Add vertical bar ("|") to CSF strings after orbitals 1 to K.
+        This could make these labels more readable'''
+    )
+    ap.add_argument(
+        '--csv', metavar='FILE',
+        help='''Save results to FILE in csv format (with semicolon as separator)'''
+    )
+    ap.add_argument(
+        '--piechart', metavar='FILE',
+        help='''Create a pie chart and save it in FILE'''
+    )
+    ap.add_argument(
+        '--root', type=int, default=1,
+        help='''Number of root to create a pie chart.
+        Only meaningfull with --piechart.'''
+    )
+    ap.add_argument(
+        '--figsize', type=float, nargs=2,
+        default=[3.33,3.33],
+        help='''Size (in inch) of the piechart.
+        Only meaningfull with --piechart.'''
+    )
+    ap.add_argument(
+        '--colordict', choices=['CSR2026', 'IC2023'],
+        help='''Choice of colordict for the piechart'''
+    )
+    ap.add_argument(
+        '--version', action='version',
+        version='%(prog)s {version}'.format(version=__version__)
+    )
+    args = ap.parse_args()
+    cidata = readci(args.molcas_output)
+    kwargs = dict(
+        korb=args.k,
+        after=args.after,
+        nelec=args.nelec,
+        spin=args.spin,
+        thresh=args.thresh,
+        roman=args.roman,
+        add_bar=args.add_bar,
+    )
+    if args.csv:
+        df = analyze(
+            cidata,
+            **kwargs
+        )
+        df.to_csv(args.csv,sep=';')
+    else:
+        analyze(
+            cidata,
+            outfile=sys.stdout,
+            **kwargs
+        )
+    if args.piechart:
+        df = analyze(
+            cidata,
+            **kwargs
+        )
+        fig, ax = plt.subplots(figsize=args.figsize)
+        piechart(
+            ax,
+            data=df[df['root']==args.root],
+            colordict=args.colordict,
+        )
+        fig.savefig(args.piechart, bbox_inches='tight')

qcmr_vbcas-0.5.1/src/qcmr/vbcas/error.py

@@ -0,0 +1,8 @@
+class VBCASError(Exception):
+    """Errors raised by vbcas"""
+
+class VBCASTypeError(VBCASError,TypeError):
+    """Type errors raised by vbcas"""
+
+class VBCASValueError(VBCASError,ValueError):
+    """Value errors raised by vbcas"""

qcmr_vbcas-0.5.1/src/qcmr/vbcas/vbcas.py

@@ -0,0 +1,356 @@
+from wrapfile import TextFileReader, TextFileWriter
+from collections import namedtuple
+import re
+import roman
+import pandas as pd
+import numpy as np
+from .error import VBCASTypeError, VBCASValueError
+
+rstart = re.compile('^ +printout of CI-coefficients larger than .+ for root *(?P<n>[0123456789]+)')
+
+ConfigItem = namedtuple(
+    'ConfigItem', ['ii', 'conf', 'coeff', 'weight']
+)
+
+def readci(
+        filepath_or_buf,
+        recompute_weights=True,
+    ):
+    """Read CI expansion from Molcas RASSCF output
+
+    Parameters:
+    -----------
+    filepath_or_buf : str, path-like or file-like
+         a file or a path to file containing output
+         from Molcas RASSCF calculations
+
+    recompute_weights : bool (optional, default: True)
+         recompute small weights from squared coeffcients.
+         This is beneficial for the accuracy for weigths
+         below 0.25.
+
+    Returns:
+    --------
+    results : pandas.DataFrame
+         CI results as dataframe with the following columns:
+         'root', 'ii', 'conf', 'coeff', 'weight'.
+    """
+    results = {
+        'root': [],
+        'ii': [],
+        'conf': [],
+        'coeff': [],
+        'weight': []
+    }
+    ready = False
+    with TextFileReader(filepath_or_buf) as f:
+        for l in f.readlines():
+            if ready:
+                if skip > 0:
+                    skip -= 1
+                elif skip == 0:
+                    ll = l.split()
+                    if not ll:
+                        ready = False
+                        continue
+                    weight = float(ll[-1])
+                    coeff = float(ll[-2])
+                    if recompute_weights:
+                        # coeff < 1/2, recompute weight
+                        # from coeff to reduce error
+                        # (this comes from error propagation:
+                        # w = c^2, so err(w) = 2*c*err(c);
+                        # and both are printed to the same accuracy
+                        if weight < 0.25:
+                            weight = coeff**2
+                    ii = int(ll[0])
+                    conf = ''.join(ll[1:-2])
+                    results['root'].append(n)
+                    results['ii'].append(ii)
+                    results['conf'].append(conf)
+                    results['coeff'].append(coeff)
+                    results['weight'].append(weight)
+            elif m := rstart.match(l):
+                n = int(m.group('n'))
+                ready = True
+                skip = 2
+        results = pd.DataFrame(results)
+        if results.empty:
+            raise VBCASValueError(
+                f"Cannot read a CI expansion from {filepath_or_buf}"
+            )
+        return results
+
+class Counter:
+    def __call__(self, conf):
+        raise NotImplementedError
+
+class ElectronCounter(Counter):
+    def __init__(self, k, after=False):
+        self.k = k
+        self.after = after
+    def __call__(self, conf):
+        n = 0
+        if self.after:
+            c = conf[self.k:]
+        else:
+            c = conf[:self.k]
+        for i in c:
+            if i == '2':
+                n += 2
+            elif i == 'u' or i == 'd':
+                n += 1
+        return n
+
+class ChargeCounter(ElectronCounter):
+    def __init__(self, k, n, after=False):
+        super().__init__(k, after)
+        self.n = n
+    def __call__(self, conf):
+        n = super().__call__(conf)
+        return self.n - n
+
+class SpinCounter(Counter):
+    def __init__(self, k):
+        self.k = k
+    def __call__(self, conf):
+        s = 0
+        for i in conf[:self.k]:
+            if i == 'u':
+                s += 1
+            elif i == 'd':
+                s -= 1
+        return s/2
+
+def oxstate(n):
+    if n < 0:
+        return '-' + roman.toRoman(-n)
+    elif n == 0:
+        return '0'
+    else: # n > 0
+        return roman.toRoman(n)
+
+    
+def analyze(
+    cidata, korb, after=False,
+    nelec=None, spin=False, thresh=None,
+    outfile=None, fmt="%-20s %5.2f%%",
+    roman=False,
+    add_bar=False):
+    """VB-CAS analysis
+
+    Parameters:
+    -----------
+    cidata : pd.DataFrame
+        CI data in the dataframe obtained from readci()
+
+    korb : int
+        number of orbitals to count electrons (and spins) in a CSF
+
+    after : bool (optional)
+        If True, the number of electrons or charge will be calculated
+        for orbitals after korb ([korb:]). 
+        Otherwise this is calculated for orbitals 1 to korb-th
+        ([:korb]).
+
+    nelec : int (optional)
+        number of electrons to assign a zeroth charge
+
+    spin : bool (optional, default False)
+        if True, also count electrons' spin
+
+    thresh : float (optional)
+        if set, will print individual contributions
+        with weights greater than this value.
+        Only applicable if outfile is set.
+
+    outfile : path-like or file-like (optional)
+        the file to write results to.
+        If not defined, the results are returned as dict.
+
+    roman : bool (optional)
+        Format oxidation state using Roman numbers.
+        Only applicable if nelec was used.
+
+    add_bar : bool (optional)
+        Add bar to CSF after k-th orbital to improve
+        readability.
+
+    fmt : str, format-spec (optional)
+        the format for analysis output.
+        Only applicable if outfile is set.
+
+    Returns:
+    -------
+    None or pd.DataFrame
+        If `outfile` is not defined, return pandas.DataFrame
+        with the analysis results. Otherwise return None.
+
+    """
+    if not isinstance(cidata, pd.DataFrame):
+        raise VBCASTypeError(
+            f"Argument `cidata` must be DataFrame, not {type(cidata)}"
+        )
+    results = cidata.copy()
+    # determine how CSFs will be classified
+    if nelec:
+        cc = ChargeCounter(korb, nelec, after)
+    else:
+        cc = ElectronCounter(korb, after)
+    if spin:
+        sc = SpinCounter(korb)
+    else:
+        sc = None
+    if sc:
+        f = lambda x: (cc(x),sc(x))
+    else:
+        f = cc
+    results['class'] = results['conf'].map(f)
+    del f
+    # aggregate CSF belonging to the same class
+    z = results[
+        ['root','class','weight']
+    ].groupby(
+        ['root','class']
+    ).agg('sum')
+    # possible formatting of individual CSFs
+    if add_bar:
+        fmt_conf = lambda conf: conf[:korb] + '|' + conf[korb:]
+    else:
+        fmt_conf = lambda conf: conf
+    def fmt_conf_list(conf_list):
+        return [fmt_conf(x) for x in conf_list]
+    # selected CSF belonging to the same class
+    t = results[results['weight'] >= thresh][
+        ['root','class','conf','coeff']
+    ].groupby(
+        ['root','class']
+    ).agg({'conf': fmt_conf_list, 'coeff': list})
+    df = pd.concat([z,t], axis=1).reset_index()
+    del z, t
+    # final formatting of charges
+    if nelec and roman:
+        chrg = oxstate
+    else:
+        chrg = lambda x: x
+    if sc:
+        f = lambda x: (chrg(x[0]),x[1])
+    else:
+        f = lambda x: chrg(x)
+    df['class'] = df['class'].map(f)
+    # textual report ...
+    if outfile:
+        df = df.set_index(['root','class'])
+        with TextFileWriter(outfile) as f:
+            # loop over roots
+            for n in df.index.levels[0]:
+                print(f'* root {n:2d}', file=f)
+                df_tmp = df.loc[n].reset_index()
+                w = 0
+                for i,r in df_tmp.iterrows():
+                    print(
+                        fmt %(
+                            r['class'],
+                            r['weight']*100
+                        ),
+                        file=f
+                    )
+                    if pd.api.types.is_list_like(r['conf']):
+                        for conf,coeff in zip(
+                                r['conf'],
+                                r['coeff']
+                            ):
+                            print(
+                                '..   ' + fmt %(conf,100*coeff**2),
+                                file=f
+                            )
+                    w += r['weight']
+                residue = 1 - w
+                print(fmt %('residue', (1-w)*100), file=f)
+                print(file=f)
+    else: # ... or return data for analysis
+        # class being a tuple is problematic for .loc
+        # so lets split it into two columns
+        if sc:
+            df.insert(2, 'spin', df['class'].map(lambda x: x[1]))
+            df['class'] = df['class'].map(lambda x: x[0])
+        return df
+
+COLORDICT = {
+    'CSR2026':  {
+        1:  '#149FE0',
+        0: '#AF977A',
+        -1:  '#FD191F',
+        'residue': 'white',
+    }, # doi: 10.1039/D5CS00346F, Fig. 36
+    'IC2023': {
+        1: '#0F64FB',
+        0: '#82CF22',
+        -1: '#FE9E27',
+        -2: '#B8FEFE',
+        'residue': 'white',
+    }, # doi: 10.1021/acs.inorgchem.3c03689, Fig. 3
+}
+
+def piechart(
+    ax, data,
+    labeldict=None,
+    colordict=None,
+    thresh_show=0.01,
+    thresh_residue=0.01,
+    residue_label='residue',
+    autopct='%1.0f%%',
+    text_color='black',
+    text_fontsize=12,
+    text_weight='bold',
+    autopct_color='white',
+    autopct_fontsize=12,
+    autopct_weight='bold',
+    pie_kwargs={},
+):
+    if type(colordict) == str:
+        colordict = COLORDICT[colordict]
+    sizes = []
+    labels = []
+    colors = []
+    if 'spin' in data.columns:
+        cs = zip(data['class'],data['spin'])
+    else:
+        cs = data['class']
+    for c,w in zip(cs,data['weight']):
+        if w >= thresh_show:
+            sizes.append(w)
+            if labeldict:
+                labels.append(labeldict[c])
+            else:
+                labels.append(str(c))
+            if colordict:
+                colors.append(colordict[c])
+    w = list(data['weight'])
+    r = 1 - sum(w)
+    if r > thresh_residue:
+        sizes.append(r)
+        labels.append(residue_label)
+        if colordict:
+            colors.append(colordict[residue_label])
+    if not colors:
+        colors = None
+    wedge_properties = {
+        'edgecolor': 'black',
+        'linewidth': 0.7
+    }
+    wedges, texts, autopct_texts = ax.pie(
+        sizes, labels=labels, colors=colors,
+        autopct=autopct,
+        wedgeprops=wedge_properties,
+        **pie_kwargs,
+    )
+    for text in texts:
+        text.set_color(text_color)
+        text.set_fontsize(text_fontsize)
+        text.set_weight(text_weight)
+    for text in autopct_texts:
+        text.set_color(autopct_color)
+        text.set_fontsize(autopct_fontsize)
+        text.set_weight(autopct_weight)
+    return wedges, texts, autopct_texts

qcmr_vbcas-0.5.1/tests/data/incorrect.out

@@ -0,0 +1,2 @@
+Incorrect data.
+No CI expansion.

qcmr_vbcas-0.5.1/tests/test_vbcas.py

@@ -0,0 +1,127 @@
+import pathlib
+import gzip
+import pytest
+import numpy as np
+import pandas as pd
+
+from qcmr.vbcas import readci, analyze
+from qcmr.vbcas.error import VBCASValueError
+
+p = pathlib.Path(__file__).parent
+
+def test_readci():
+    with gzip.open(p/'data'/'ex1.out.gz', 'rt') as f:
+        r = readci(f)
+    # test if there are roots 1 to 6
+    assert set(r['root']) == set(range(1,7))
+    # tests lengths of CI expansions
+    assert len(r[r['root']==1]) == 7
+    assert len(r[r['root']==2]) == 7
+    assert len(r[r['root']==3]) == 7
+    assert len(r[r['root']==4]) == 8
+    assert len(r[r['root']==5]) == 10
+    assert len(r[r['root']==6]) == 8
+    # test selected items
+    x = r[r['root']==1].reset_index().iloc[0]
+    assert x.conf == '22200'
+    assert x.coeff == pytest.approx(0.29609, abs=1e-5)
+    assert x.weight == pytest.approx(0.08767, abs=1e-5)
+    y = r[r['root']==5].reset_index().iloc[9]
+    assert y.conf == '022ud'
+    assert y.coeff == pytest.approx(0.06341, abs=1e-5)
+    assert y.weight == pytest.approx(0.00402, abs=1e-5)
+
+def test_readci__filepath_or_buf():
+    filepath = p/'data'/'ex1.out.gz'
+    with gzip.open(filepath, 'rt') as f:
+        r1 = readci(f)
+    r2 = readci(filepath)
+    assert r1.equals(r2)
+
+def test_readci__incorrect_data():
+    try:
+        readci(p/'data'/'incorrect.out')
+        assert False
+    except VBCASValueError:
+        pass
+
+def test_analyze():
+    with gzip.open(p/'data'/'ex1.out.gz', 'rt') as f:
+        r = readci(f)
+    a = analyze(r, 3)
+    
+    # tests number of roots
+    assert set(a['root'].unique()) == set(range(1,7))
+    
+    # test classes for some roots
+    assert not a[(a['root']==1) & (a['class']==6)].empty
+    assert not a[(a['root']==1) & (a['class']==5)].empty
+    assert not a[(a['root']==1) & (a['class']==4)].empty
+    assert a[(a['root']==2) & (a['class']==6)].empty
+    assert not a[(a['root']==2) & (a['class']==5)].empty
+    assert not a[(a['root']==2) & (a['class']==4)].empty
+
+    # tests weights for selected items
+    a = a.set_index(['root','class'])
+    assert a.loc[1,6].weight == pytest.approx(0.08767, abs=1e-5)
+    assert a.loc[1,5].weight == pytest.approx(0.82442, abs=1e-5)
+    assert a.loc[1,4].weight == pytest.approx(0.08461, abs=1e-5)
+    assert a.loc[2,4].weight == pytest.approx(0.06398, abs=1e-5)
+
+    # all items in coeff should be N/A
+    assert a['coeff'].isna().all()
+
+def test_analyze_charge():
+    with gzip.open(p/'data'/'ex1.out.gz', 'rt') as f:
+        r = readci(f)
+    a = analyze(r, 3, nelec=8).set_index(['root','class'])
+    assert a.loc[1,3].weight == pytest.approx(0.82442, abs=1e-5)
+
+def test_analyze_charge_spin_thresh():
+    with gzip.open(p/'data'/'ex1.out.gz', 'rt') as f:
+        r = readci(f)
+    #
+    a = analyze(r, 3, nelec=8, spin=True, thresh=0.1).set_index(
+        ['root','class','spin']
+    )
+    assert a.loc[1,3,0.5].weight == pytest.approx(0.82442, abs=1e-5)
+    assert a.loc[1,3,0.5].conf == ['2u20d', 'u22d0']
+    assert a.loc[1,4,1.0].weight == pytest.approx(0.05516, abs=1e-5)
+    assert np.isnan(a.loc[1,4,1.0].conf)
+    #
+    a = analyze(r, 3, nelec=8, spin=True, thresh=0.00001)
+    # tests number of roots
+    assert set(a['root']) == set(range(1,7))
+
+    a = a.set_index(['root','class','spin'])
+    assert a.loc[1,2,0].weight == pytest.approx(0.08767, abs=1e-5)
+    assert a.loc[1,2,0].conf == ['22200']
+    assert a.loc[1,4,1].weight == pytest.approx(0.05516, abs=1e-5)
+    assert a.loc[1,4,1].conf == ['uu2dd']
+    assert a.loc[1,4,1].coeff[0] == pytest.approx(-0.23486, abs=1e-5)
+    assert a.loc[6,3,0.5].weight == pytest.approx(0.96759, abs=1e-5)
+    assert a.loc[6,3,0.5].conf[0] == '2u2d0'
+    assert a.loc[6,3,0.5].conf[3] == 'u220d'
+
+
+def test_analyze_dataframe():
+    r = readci(p/'data'/'ex1.out.gz')
+    df = analyze(r, 3, nelec=8)
+    t = df[df['root']==1]
+    assert len(t['class']) == 3
+    for c,w in zip(t['class'],t['weight']):
+        if c == 2:
+            assert w == pytest.approx(0.08767, abs=1e-5)
+        elif c == 3:
+            assert w == pytest.approx(0.82442, abs=1e-5)
+        elif c == 4:
+            assert w == pytest.approx(0.08461, abs=1e-5)
+    df = analyze(r, 3, nelec=8, roman=True)
+    t = df[df['root']==2]
+    assert len(t['class']) == 2
+    for c,w in zip(t['class'],t['weight']):
+        if c == 'III':
+            assert w == pytest.approx(0.93471, abs=1e-5)
+        elif c == 'IV':
+            assert w == pytest.approx(0.06398, abs=1e-5)
+    assert list(t['class']) == ['III', 'IV']