Merge pull request #263 from ktwalsh/devel

Added single excitation specific functions to citools

Author: alexvakimov

src/libra_py/citools/interfaces.py

@@ -163,6 +163,76 @@ def build_minimal_csf_basis(
 
     return min_basis, transposed_basis
 
+def build_minimal_csf_basis_singlet(
+    configs: List[Tuple[int, ...]],
+    active_space: List[int],
+    nelec: int,
+    max_unpaired: int
+) -> Tuple[List[Tuple[Any, ...]], List[Tuple[Any, ...]]]:
+    """
+    Construct a minimal CSF (Configuration State Function) basis
+    from raw MOPAC/Libra configurations.
+
+    Parameters
+    ----------
+    configs : list[tuple[int]]
+        Configurations extracted from Libra or MOPAC output (raw orbital numbers).
+    active_space : list[int]
+        List of active orbital numbers defining the active space.
+    nelec : int
+        Total number of electrons.
+    max_unpaired : int
+        Twice the target spin projection (2*Ms).
+        For example, 0 corresponds to singlet-only configurations.
+
+    Returns
+    -------
+    min_basis : list[tuple]
+        List of matching determinants (CSFs) as (configuration, phase) tuples.
+    transposed_basis : list[tuple]
+        Transposed representation, i.e. `list(zip(*min_basis))`.
+        Each element groups together all configurations or all phases across the basis.
+
+    Notes
+    -----
+    - Each entry in `min_basis` corresponds to a determinant that matches
+      one of the given MOPAC configurations, within the spin constraint `max_unpaired`.
+    - `transposed_basis` is convenient for splitting the basis into
+      separate lists of determinants and phases.
+    - If no matches are found, `transposed_basis` is returned as an empty list.
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> # Example input from MOPAC/Libra
+    >>> configs0_raw = [(6, -6, 7, -7, 9, -8)]
+    >>> active_space = [6, 7, 8, 9, 10, 11]
+    >>> nelec = 6
+    >>> max_unpaired = 0   # singlet configurations only
+    >>>
+    >>> min_basis, (all_confs, all_phases) = build_minimal_csf_basis(
+    ...     configs0_raw, active_space, nelec, max_unpaired
+    ... )
+    >>>
+    >>> print(len(min_basis))
+    19
+    >>> print(all_confs[0])
+    (6, -6, 7, -7, 8, -8)
+    >>> print(all_phases[0])
+    1
+    """
+
+    # Generate all possible determinants (with parity) for the given active space
+#    dets: List[Tuple[Any, ...]] = list(sd.generate_determinants_with_parity(active_space, nelec))
+
+    min_basis: List[Tuple[Any, ...]] = []
+    for det, phase in sd.generate_single_excitations(active_space, nelec):
+        min_basis.append((det, phase))
+
+    # Avoid error when basis is empty
+    transposed_basis: List[Tuple[Any, ...]] = list(zip(*min_basis)) if min_basis else []
+
+    return min_basis, transposed_basis
 
 
 
@@ -392,3 +462,72 @@ def configs_and_T_matrix(
     return mapped_basis, T
 
 
+def configs_and_T_matrix_singlet(
+    configs0_raw: List[Tuple[int, ...]],
+    active_space: List[int],
+    orbital_space: List[int],
+    nelec: int,
+    S: int,
+    Ms: int
+) -> Tuple[List[Tuple[int, ...]], "CMATRIX"]:
+    """
+    Generate the minimal active-space configurations mapped to a given orbital space
+    and the configuration-to-CSF transformation matrix for a CAS with given spin.
+
+    Parameters
+    ----------
+    configs0_raw : list[tuple[int]]
+        List of raw configurations from Libra/MOPAC (signed orbital indices).
+    active_space : list[int]
+        Orbitals defining the active space used to generate the minimal determinant basis.
+    orbital_space : list[int]
+        Orbital indices used for mapping configurations (output will be relative to this space).
+    nelec : int
+        Number of active electrons.
+    S : int
+        Total spin quantum number.
+    Ms : int
+        Spin projection quantum number.
+
+    Returns
+    -------
+    mapped_basis : list[tuple[int, ...]]
+        List of minimal configurations mapped to the specified `orbital_space`,
+        with signs preserved (positive = α-spin, negative = β-spin).
+    T : CMATRIX
+        Complex-valued configuration-to-CSF transformation matrix.
+
+    Example
+    -------
+    >>> # Build configurations and T matrix for singlet CAS
+    >>> mapped_basis, T = configs_and_T_matrix(
+    ...     configs0_raw,
+    ...     active_space=[6, 7, 8, 9, 10, 11],
+    ...     orbital_space=[2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+    ...     nelec=6,
+    ...     S=0,
+    ...     Ms=0
+    ... )
+    >>> # mapped_basis shows minimal determinants mapped to orbital_space indices
+    >>> print(mapped_basis[:5])
+    [(5, -5, 6, -6, 7, -7),
+     (5, -5, 6, -6, 7, -8),
+     (5, -5, 6, -6, -7, 8),
+     (5, -5, 6, -6, 7, -9),
+     (5, -5, 6, -6, -7, 9)]
+    >>> # T is the configuration-to-CSF transformation matrix
+    >>> print("Shape of T:", T.num_of_rows, "x", T.num_of_cols)
+    """
+
+    # 1. Build minimal SD basis with spin constraint 2*Ms
+    min_basis, (all_confs, all_phases) = build_minimal_csf_basis_singlet(
+        configs0_raw, active_space, nelec, 2*Ms
+    )
+
+    # 2. Map configurations to the specified orbital space
+    mapped_basis = map_to_active_indices(all_confs, orbital_space)
+
+    # 3. Compute configuration-to-CSF transformation matrix
+    T = conf2csf_matrix(min_basis, all_confs, all_phases, S, Ms)
+
+    return mapped_basis, T

src/libra_py/citools/slatdet.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 # *********************************************************************************
 # * Copyright (C) 2025 Alexey V. Akimov
 # *
@@ -214,7 +215,69 @@ def generate_determinants_with_parity(
         parity: int = permutation_parity(original, sorted_combo)
         yield sorted_combo, parity
 
+def generate_single_excitations(active_orbitals: List[int], nelec: int):
+    """
+    Generate the ground-state determinant first, followed by all single-excitation
+    determinants (sorted + parity), for a closed-shell reference inside an active space.
+
+    Parameters
+    ----------
+    active_orbitals : list[int]
+        Ordered list of spatial orbital numbers in the active space.
+        Example: [1,2,3,4,5,6,7,8,9,10]
 
+    nelec : int
+        Number of electrons in the active space. Must be even for closed-shell.
+        Example: 10 -> 5 occupied spatial orbitals (paired).
+
+    Yields
+    ------
+    (det_sorted, parity)
+        det_sorted: tuple of signed spin-orbitals (canonical order)
+        parity: +1 or -1
+    """
+    if nelec % 2 != 0:
+        raise ValueError("Closed-shell reference requires an even number of electrons.")
+
+    n_occ = nelec // 2
+    occ = active_orbitals[:n_occ]
+    virt = active_orbitals[n_occ:]
+
+    # -----------------------------
+    # 1. Ground state determinant
+    # -----------------------------
+    ref_raw = []
+    for o in occ:
+        ref_raw.append(+o)  # alpha
+        ref_raw.append(-o)  # beta
+
+    ref_sorted = tuple(sorted(ref_raw, key=canonical_sort_key))
+    ref_parity = permutation_parity(tuple(ref_raw), ref_sorted)
+
+    # yield ground-state first
+    yield ref_sorted, ref_parity
+
+    # -----------------------------
+    # 2. Single excitations
+    # -----------------------------
+    for o in occ:
+        for v in virt:
+
+            # α-spin excitation: +o → +v
+            det_raw = list(ref_raw)
+            det_raw.remove(+o)
+            det_raw.append(+v)
+            det_sorted = tuple(sorted(det_raw, key=canonical_sort_key))
+            parity = permutation_parity(tuple(det_raw), det_sorted)
+            yield det_sorted, parity
+
+            # β-spin excitation: -o → -v
+            det_raw = list(ref_raw)
+            det_raw.remove(-o)
+            det_raw.append(-v)
+            det_sorted = tuple(sorted(det_raw, key=canonical_sort_key))
+            parity = permutation_parity(tuple(det_raw), det_sorted)
+            yield det_sorted, parity
 
 def slater_overlap_matrix(dets_A, dets_B, S_orb, complex_valued=False):
     """