TB2J 0.9.9rc10__tar.gz → 0.9.9rc11__tar.gz

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TB2J
-Version: 0.9.9rc10
+Version: 0.9.9rc11
 Summary: TB2J: First principle to Heisenberg exchange J using tight-binding Green function method
 Author: Xu He
 Author-email: mailhexu@gmail.com

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/TB2J/exchange.py

@@ -1,6 +1,6 @@
 import os
 import pickle
-from collections import OrderedDict, defaultdict
+from collections import defaultdict
 
 import numpy as np
 from tqdm import tqdm
@@ -96,78 +96,96 @@ class Exchange(ExchangeParams):
 
     def _prepare_orb_dict(self):
         """
-        generate self.ind_mag_atoms and self.orb_dict
-        """
-        # adict: dictionary of {'Fe': ['dxy', 'dyz', ...], ...}
-        adict = OrderedDict()
-        # orb_dict: {ind_atom:[ind_orb,1,2], ...}
-        self.orb_dict = {}
-        # labels: {0:{dxy, ...}}
-        self.labels = {}
-        # magnetic atoms index
-        self.ind_mag_atoms = []
-
-        sdict = symbol_number(self.atoms)
-
-        for i, base in enumerate(self.basis):
-            if i not in self.exclude_orbs:
-                # e.g. Fe2, dxy, _, _
-                if isinstance(base, str):
-                    atom_sym, orb_sym = base.split("|")[:2]
-                    iatom = sdict[atom_sym]
-                else:
-                    try:
-                        atom_sym, orb_sym = base[:2]
-                        iatom = sdict[atom_sym]
-                    except Exception:
-                        iatom = base.iatom
-                        atom_sym = base.iatom
-                        orb_sym = base.sym
-
-                if atom_sym in adict:
-                    adict[atom_sym].append(orb_sym)
-                else:
-                    adict[atom_sym] = [orb_sym]
-                if iatom not in self.orb_dict:
-                    self.orb_dict[iatom] = [i]
-                    self.labels[iatom] = [orb_sym]
-                else:
-                    self.orb_dict[iatom] += [i]
-                    self.labels[iatom] += [orb_sym]
+        Generate orbital and magnetic atom mappings needed for exchange calculations.
 
-        # index of magnetic atoms
-        symbols = self.atoms.get_chemical_symbols()
-        tags = self.atoms.get_tags()
-        for i, (sym, tag) in enumerate(zip(symbols, tags)):
-            if sym in self.magnetic_elements or f"{sym}{tag}" in self.magnetic_elements:
-                self.ind_mag_atoms.append(i)
+        Creates:
+        - self.orb_dict: Maps atom indices to their orbital indices
+        - self.labels: Maps atom indices to their orbital labels
+        - self.ind_mag_atoms: List of indices of magnetic atoms
+        - self._spin_dict: Maps atom indices to spin indices
+        - self._atom_dict: Maps spin indices back to atom indices
+        """
+        self._create_orbital_mappings()
+        self._identify_magnetic_atoms()
+        self._validate_orbital_assignments()
+        self._create_spin_mappings()
+        self._prepare_orb_mmat()
 
-        # sanity check to see if some magnetic atom has no orbital.
-        for iatom in self.ind_mag_atoms:
-            if iatom not in self.orb_dict:
+    def _create_orbital_mappings(self):
+        """Create mappings between atoms and their orbitals."""
+        self.orb_dict = {}  # {atom_index: [orbital_indices]}
+        self.labels = {}  # {atom_index: [orbital_labels]}
+        atom_symbols = symbol_number(self.atoms)
+
+        for orb_idx, base in enumerate(self.basis):
+            if orb_idx in self.exclude_orbs:
+                continue
+
+            # Extract atom and orbital info
+            if isinstance(base, str):
+                atom_sym, orb_sym = base.split("|")[:2]
+                atom_idx = atom_symbols[atom_sym]
+            else:
+                try:
+                    atom_sym, orb_sym = base[:2]
+                    atom_idx = atom_symbols[atom_sym]
+                except Exception:
+                    atom_idx = base.iatom
+                    atom_sym = base.iatom
+                    orb_sym = base.sym
+
+            # Update orbital mappings
+            if atom_idx not in self.orb_dict:
+                self.orb_dict[atom_idx] = [orb_idx]
+                self.labels[atom_idx] = [orb_sym]
+            else:
+                self.orb_dict[atom_idx].append(orb_idx)
+                self.labels[atom_idx].append(orb_sym)
+
+    def _identify_magnetic_atoms(self):
+        """Identify which atoms are magnetic based on elements/tags."""
+        if self.index_magnetic_atoms is not None:
+            self.ind_mag_atoms = self.index_magnetic_atoms
+        else:
+            self.ind_mag_atoms = []
+            symbols = self.atoms.get_chemical_symbols()
+            tags = self.atoms.get_tags()
+
+            for atom_idx, (sym, tag) in enumerate(zip(symbols, tags)):
+                if (
+                    sym in self.magnetic_elements
+                    or f"{sym}{tag}" in self.magnetic_elements
+                ):
+                    self.ind_mag_atoms.append(atom_idx)
+        print(f"Magnetic atoms: {self.ind_mag_atoms}")
+
+    def _validate_orbital_assignments(self):
+        """Validate that magnetic atoms have proper orbital assignments."""
+        # Check all magnetic atoms have orbitals
+        for atom_idx in self.ind_mag_atoms:
+            if atom_idx not in self.orb_dict:
                 raise ValueError(
-                    f"""Cannot find any orbital for atom {iatom}, which is supposed to be magnetic. Please check the Wannier functions."""
+                    f"Atom {atom_idx} is magnetic but has no orbitals assigned. "
+                    "Check Wannier function definitions."
                 )
+
+        # For non-collinear case, check spin-orbital pairing
         if not self._is_collinear:
-            for iatom, orb in self.orb_dict.items():
-                # print(f"iatom: {iatom}, orb: {orb}")
-                nsorb = len(self.orb_dict[iatom])
-                if nsorb % 2 != 0 and False:
+            for atom_idx, orbitals in self.orb_dict.items():
+                if len(orbitals) % 2 != 0:
                     raise ValueError(
-                        f"""The number of spin-orbitals for atom {iatom} is not even,
-{nsorb} spin-orbitals are found near this atom.
-which means the spin up/down does not have same number of orbitals.
-This is often because the Wannier functions are wrongly defined,
-or badly localized. Please check the Wannier centers in the Wannier90 output file.
-"""
+                        f"Atom {atom_idx} has {len(orbitals)} spin-orbitals "
+                        "(should be even). Check Wannier function localization."
                     )
-        self._spin_dict = {}
-        self._atom_dict = {}
-        for ispin, iatom in enumerate(self.ind_mag_atoms):
-            self._spin_dict[iatom] = ispin
-            self._atom_dict[ispin] = iatom
 
-        self._prepare_orb_mmat()
+    def _create_spin_mappings(self):
+        """Create mappings between atom indices and spin indices."""
+        self._spin_dict = {}  # {atom_index: spin_index}
+        self._atom_dict = {}  # {spin_index: atom_index}
+
+        for spin_idx, atom_idx in enumerate(self.ind_mag_atoms):
+            self._spin_dict[atom_idx] = spin_idx
+            self._atom_dict[spin_idx] = atom_idx
 
     def _prepare_orb_mmat(self):
         self.mmats = {}

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/TB2J/exchange_params.py

@@ -15,6 +15,7 @@ class ExchangeParams:
     efermi: float
     basis = []
     magnetic_elements = []
+    index_magnetic_atoms = None
     include_orbs = {}
     _kmesh = [4, 4, 4]
     emin: float = -15
@@ -55,6 +56,7 @@ class ExchangeParams:
         mae_angles=None,
         orth=False,
         ibz=False,
+        index_magnetic_atoms=None,
     ):
         self.efermi = efermi
         self.basis = basis
@@ -79,6 +81,7 @@ class ExchangeParams:
         self.mae_angles = mae_angles
         self.orth = orth
         self.ibz = ibz
+        self.index_magnetic_atoms = index_magnetic_atoms
 
     def set_params(self, **kwargs):
         for key, val in kwargs.items():
@@ -229,6 +232,21 @@ def add_exchange_args_to_parser(parser: argparse.ArgumentParser):
         default=False,
     )
 
+    parser.add_argument(
+        "--mae_angles",
+        help="angles for computing MAE, default is 0 0 0",
+        type=float,
+        nargs="*",
+        default=[0.0, 0.0, 0.0],
+    )
+    parser.add_argument(
+        "--index_magnetic_atoms",
+        help="index of magnetic atoms in the unit cell, default is None. If specified, this will be used to determine the atoms to be considered as magnetic atoms, instead of determined from magnetic elements. Note that the index starts from 1 ",
+        type=int,
+        nargs="*",
+        default=None,
+    )
+
     return parser
 
 
@@ -250,4 +268,5 @@ def parser_argument_to_dict(args) -> dict:
         "orb_decomposition": args.orb_decomposition,
         "output_path": args.output_path,
         "orth": args.orth,
+        "index_magnetic_atoms": args.index_magnetic_atoms,
     }

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/TB2J/rotate_siestaDM.py

@@ -1,27 +1,28 @@
 import sisl
 
-def rotate_siesta_DM(DM, noncollinear=False):
 
-    angles_list = [ [0.0, 90.0, 0.0], [0.0, 90.0, 90.0] ]
+def rotate_siesta_DM(DM, noncollinear=False):
+    angles_list = [[0.0, 90.0, 0.0], [0.0, 90.0, 90.0]]
     if noncollinear:
         angles_list += [[0.0, 45.0, 0.0], [0.0, 90.0, 45.0], [0.0, 45.0, 90.0]]
 
     for angles in angles_list:
         yield DM.spin_rotate(angles)
 
+
 def read_label(fdf_fname):
-    label = 'siesta'
-    with open(fdf_fname, 'r') as File:
+    label = "siesta"
+    with open(fdf_fname, "r") as File:
         for line in File:
-            corrected_line = line.lower().replace('.', '').replace('-', '')
-            if 'systemlabel' in corrected_line:
+            corrected_line = line.lower().replace(".", "").replace("-", "")
+            if "systemlabel" in corrected_line:
                 label = line.split()[1]
                 break
 
     return label
 
-def rotate_DM(fdf_fname, noncollinear=False):
 
+def rotate_DM(fdf_fname, noncollinear=False):
     fdf = sisl.get_sile(fdf_fname)
     DM = fdf.read_density_matrix()
     label = read_label(fdf_fname)
@@ -32,4 +33,6 @@ def rotate_DM(fdf_fname, noncollinear=False):
         rotated_DM.write(f"{label}_{i+1}.DM")
     DM.write(f"{label}_0.DM")
 
-    print(f"The output has been written to the {label}_i.DM files. {label}_0.DM contains the reference density matrix.")
+    print(
+        f"The output has been written to the {label}_i.DM files. {label}_0.DM contains the reference density matrix."
+    )

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/TB2J.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TB2J
-Version: 0.9.9rc10
+Version: 0.9.9rc11
 Summary: TB2J: First principle to Heisenberg exchange J using tight-binding Green function method
 Author: Xu He
 Author-email: mailhexu@gmail.com

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/docs/src/Contributors.rst

@@ -1,7 +1,7 @@
 Contributors
 ============
 
-The TB2J package is initially developped:
+The TB2J package is initially developed:
 
 * Xu He (mailhexu@gmail.com)
 

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/docs/src/ReleaseNotes.md

@@ -11,7 +11,9 @@ This currently requires an non-official SIESTA branch which can seperate the spi
 
 - An improved method of the downfolding method which implements the ligand correction to the exchange based on the Wannier function method. This requires the updated version of LaWaF (https://github.com/mailhexu/lawaf) and the updated version of the TB2J\_downfold.py script.
 
-- There is a major refractoring of the interface to the DFT codes. The parsing of the electron Hamiltonian from the DFT codes are now in a separate python package called HamiltonIO (github.com/mailhexu/HamiltonIO). This package is used by TB2J but is made general to be used with other packages too.
+- Added a new parameter (--index_magnetic_atoms) to the wann2J.py, siesta2J.py, and abacus2J.py scripts, so that a more detailed selection of the magnetic atoms than the one in --element is possible. This is useful when we need to select a subset of a specific element in a system.
+
+- There is a major refactoring of the interface to the DFT codes. The parsing of the electron Hamiltonian from the DFT codes are now in a separate python package called HamiltonIO (github.com/mailhexu/HamiltonIO). This package is used by TB2J but is made general to be used with other packages too.
 
 
 #### v0.11.0 October 10, 2024

tb2j-0.9.9rc11/docs/src/parameters.rst

@@ -0,0 +1,89 @@
+Parameters for Magnetic Interaction Calculations
+=============================================
+
+Introduction
+-----------
+TB2J provides several command-line tools to calculate magnetic interactions from different electronic structure codes. Each tool shares a common set of parameters for controlling the magnetic interaction calculations, while also having some tool-specific parameters.
+
+To view the complete list of parameters for any tool, use the --help option:
+
+::
+
+   wann2J.py --help    # For Wannier90-based calculations
+   siesta2J.py --help  # For SIESTA-based calculations
+   abacus2J.py --help  # For ABACUS-based calculations
+
+Common Parameters
+---------------
+These parameters are available across all TB2J tools and control the core aspects of magnetic interaction calculations.
+
+System Definition
+^^^^^^^^^^^^^^^
+* elements: List of magnetic elements to include in the Heisenberg model. Example: ``--elements Fe Ni``
+
+* index_magnetic_atoms: Explicitly specify magnetic atoms by their indices (starting from 1) in the unit cell. Overrides element-based selection. Example: ``--index_magnetic_atoms 1 2 4``
+
+* exclude_orbs: Zero-based indices of orbitals to exclude from magnetic site calculations. Useful for fine-tuning the magnetic model.
+
+K-space and Real Space Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* kmesh: Three integers defining the Monkhorst-Pack k-point mesh (e.g., ``--kmesh 7 7 7``). This mesh determines:
+   - The k-points used for Green's function calculations
+   - The real-space supercell size for magnetic interactions
+   - For example, a :math:`7 \times 7 \times 7` k-mesh creates a supercell where magnetic interactions are calculated between the central atom and all atoms within this supercell
+
+* rcut: Maximum distance (in Å) for calculating magnetic interactions between atom pairs. If not specified, includes all pairs within the supercell defined by kmesh.
+
+Energy Integration Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^
+* efermi: Fermi energy in eV. Handling varies by tool:
+   - siesta2J.py/abacus2J.py: Automatically read from output
+   - wann2J.py: Must be provided from DFT calculation
+   - For insulators: Can be within the band gap
+   - For metals: Should match the DFT value
+
+* emin, emax: Energy range for integration, relative to efermi:
+   - emin: Should be low enough to include all magnetically relevant states
+   - Check local density of states: spin up/down should be nearly identical below emin
+   - emax: Usually 0.0 (Fermi level). Can be adjusted for charge doping studies
+   - Note: Direct DFT doping is preferred over emax adjustment
+
+* nz: Number of energy points for numerical integration of :math:`\int_{emin}^{emax} d\epsilon`
+
+Performance and Output Controls
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+* np/nproc: Number of CPU cores for parallel processing. Default: 1
+
+* use_cache: Store wavefunctions and Hamiltonian on disk to reduce memory usage. Useful for large systems. Default: False
+
+* cutoff: Minimum magnitude of exchange coupling (J) to write to output (in eV). Helps filter numerical noise.
+
+* output_path: Directory for output files. Default: TB2J_results
+
+Output Customization
+^^^^^^^^^^^^^^^^
+* description: Add essential calculation details to the XML output:
+   - Exchange-correlation functional used
+   - Hubbard U values if applicable
+   - Magnetic state description
+   - Any other relevant parameters
+
+Advanced Options
+^^^^^^^^^^^^
+* orb_decomposition: Analyze orbital contributions in non-collinear calculations. Default: False
+
+* orth: Apply Löwdin orthogonalization before diagonalization. Usually for testing purposes. Default: False
+
+Tool-Specific Parameters
+---------------------
+
+SIESTA Interface (siesta2J.py)
+^^^^^^^^^^^^^^^^^^^^^^^^
+* fdf_fname: Path to SIESTA's input fdf file. Default: ./
+* fname: Output exchange parameters XML filename. Default: exchange.xml
+* split_soc: Enable reading of spin-orbit coupling from SIESTA output. Default: False
+
+ABACUS Interface (abacus2J.py)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+* path: Location of ABACUS calculation files. Default: ./
+* suffix: ABACUS calculation label (used in OUT.suffix). Default: abacus

tb2j-0.9.9rc11/scripts/abacus2J.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+import argparse
+import sys
+
+from TB2J.exchange_params import add_exchange_args_to_parser
+from TB2J.interfaces import gen_exchange_abacus
+from TB2J.versioninfo import print_license
+
+
+def run_abacus2J():
+    print_license()
+    parser = argparse.ArgumentParser(
+        description="abacus2J: Using magnetic force theorem to calculate exchange parameter J from abacus Hamiltonian in the LCAO mode"
+    )
+    # Add ABACUS specific arguments
+    parser.add_argument(
+        "--path", help="the path of the abacus calculation", default="./", type=str
+    )
+    parser.add_argument(
+        "--suffix",
+        help="the label of the abacus calculation. There should be an output directory called OUT.suffix",
+        default="abacus",
+        type=str,
+    )
+
+    # Add common exchange arguments
+    parser = add_exchange_args_to_parser(parser)
+
+    args = parser.parse_args()
+
+    if args.elements is None:
+        print("Please input the magnetic elements, e.g. --elements Fe Ni")
+        sys.exit()
+
+    # include_orbs = {}
+
+    gen_exchange_abacus(
+        path=args.path,
+        suffix=args.suffix,
+        kmesh=args.kmesh,
+        magnetic_elements=args.elements,
+        include_orbs={},
+        Rcut=args.rcut,
+        emin=args.emin,
+        nz=args.nz,
+        description=args.description,
+        output_path=args.output_path,
+        use_cache=args.use_cache,
+        nproc=args.nproc,
+        exclude_orbs=args.exclude_orbs,
+        orb_decomposition=args.orb_decomposition,
+        index_magnetic_atoms=args.index_magnetic_atoms,
+        cutoff=args.cutoff,
+    )
+
+
+if __name__ == "__main__":
+    run_abacus2J()

tb2j-0.9.9rc11/scripts/siesta2J.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+import argparse
+import sys
+
+from TB2J.exchange_params import add_exchange_args_to_parser
+from TB2J.interfaces import gen_exchange_siesta
+from TB2J.versioninfo import print_license
+
+
+def run_siesta2J():
+    print_license()
+    parser = argparse.ArgumentParser(
+        description="siesta2J: Using magnetic force theorem to calculate exchange parameter J from siesta Hamiltonian"
+    )
+    # Add siesta specific arguments
+    parser.add_argument(
+        "--fdf_fname", help="path of the input fdf file", default="./", type=str
+    )
+    parser.add_argument(
+        "--fname",
+        default="exchange.xml",
+        type=str,
+        help="exchange xml file name. default: exchange.xml",
+    )
+    parser.add_argument(
+        "--split_soc",
+        help="whether the SOC part of the Hamiltonian can be read from the output of siesta. Default: False",
+        action="store_true",
+        default=False,
+    )
+
+    # Add common exchange arguments
+    parser = add_exchange_args_to_parser(parser)
+
+    args = parser.parse_args()
+
+    if args.elements is None:
+        print("Please input the magnetic elements, e.g. --elements Fe Ni")
+        sys.exit()
+
+    # include_orbs = {}
+    # for element in args.elements:
+    #    if "_" in element:
+    #        elem = element.split("_")[0]
+    #        orb = element.split("_")[1:]
+    #        include_orbs[elem] = orb
+    #    else:
+    #        include_orbs[element] = None
+
+    gen_exchange_siesta(
+        fdf_fname=args.fdf_fname,
+        kmesh=args.kmesh,
+        # magnetic_elements=list(include_orbs.keys()),
+        # include_orbs=include_orbs,
+        magnetic_elements=args.elements,
+        include_orbs={},
+        Rcut=args.rcut,
+        emin=args.emin,
+        emax=args.emax,
+        nz=args.nz,
+        description=args.description,
+        output_path=args.output_path,
+        use_cache=args.use_cache,
+        nproc=args.np,
+        exclude_orbs=args.exclude_orbs,
+        orb_decomposition=args.orb_decomposition,
+        read_H_soc=args.split_soc,
+        orth=args.orth,
+        index_magnetic_atoms=args.index_magnetic_atoms,
+    )
+
+
+if __name__ == "__main__":
+    run_siesta2J()

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/scripts/wann2J.py

@@ -89,6 +89,7 @@ def run_wann2J():
         # qspace=args.qspace,
         write_density_matrix=args.write_dm,
         orb_decomposition=args.orb_decomposition,
+        index_magnetic_atoms=args.index_magnetic_atoms,
     )
 
 

{tb2j-0.9.9rc10 → tb2j-0.9.9rc11}/setup.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 from setuptools import find_packages, setup
 
-__version__ = "0.9.9_rc10"
+__version__ = "0.9.9rc11"
 
 long_description = """TB2J is a Python package aimed to compute automatically the magnetic interactions (superexchange  and Dzyaloshinskii-Moriya) between atoms of magnetic crystals from DFT Hamiltonian based on Wannier functions or Linear combination of atomic orbitals. It uses the Green's function method and take the local rigid spin rotation as a perturbation. The package can take the output from Wannier90, which is interfaced with many density functional theory codes or from codes based on localised orbitals. A minimal user input is needed, which allows for an easily integration into a high-throughput workflows. """
 

tb2j-0.9.9rc10/docs/src/parameters.rst

@@ -1,28 +0,0 @@
-Parameters in calculation of magnetic interaction parameters
-=============================================================
-
-List of parameters:
--------------------------------
-The list of parameter can be found using:
-
-::
-
-   wann2J.py --help
-
-or
-
-::
-
-   siesta2J.py --help
-
-The parameter will be explained in the following text.
-
-* kmesh: Three integers to specify the size of a Monkhorst-Pack mesh. This is the mesh of k-points used to calculate the Green's functions. The real space supercell in which the magnetic interactions are calculated, has the same size as the k-mesh. For example, a :math:`7 \times 7 \times` k-mesh is linked with a :math:`7 \times 7 \times` supercell, the atom :math:`i` resides in the center cell, whereas the :math:`j` atom can be in all the cells in the supercell. 
-
-* efermi: The Fermi energy in eV. For insulators, it can be inside the gap. For metals, it should be the same as in the DFT calculation. Due to the different algorithms in the integration of the density, the Fermi energy could be slightly shifted from the DFT value. 
-
-* emin, emax, and nz: During the calculation, there  is a integration :math:`\int_{emin}^{emax} d\epsilon` calculation. The emin and emax are relative values to the Fermi energy. The emax should be 0.   The emin should be low enough so that all the electronic states that affect the magnetic interactions are integrated. This can be checked with the local density of the states. Below the emin, the spin up and down density of states should be almost identical.  The nz is the number of steps in this integration.  The emax can be used to adjust the integration if we want to simulate the effect of the charge doping. This is with the approximation that there is only a rigid shift of the band structure. However, it is recommended to dope charge within the DFT then this approximation is not needed. The emax parameter will thus be deprecated soon.
-
-* rcut: rcut is the cutoff distance between two ion pairs between which the magnetic interaction parameters are calculated. By default, all the pairs inside the supercell defined by the kmesh 
-
-* exclude_orbs: the indeces of orbitals, whose contribution will not be counted in the magnetic interaction. It is a list of integers. The indices are zero based.