Merge branch 'se-init2setup'

src/sisl/physics/self_energy.py

@@ -21,7 +21,7 @@
 from sisl._internal import set_module
 from sisl.linalg import inv, linalg_info, solve
 from sisl.linalg.base import _compute_lwork
-from sisl.messages import info, warn
+from sisl.messages import deprecation, info, warn
 from sisl.physics.bloch import Bloch
 from sisl.physics.brillouinzone import MonkhorstPack
 from sisl.sparse_geometry import _SparseGeometry
@@ -687,8 +687,7 @@ class RealSpaceSE(SelfEnergy):
     >>> H = Hamiltonian(graphene)
     >>> H.construct([(0.1, 1.44), (0, -2.7)])
     >>> rse = RealSpaceSE(H, 0, 1, (3, 4, 1))
-    >>> rse.set_options(eta=1e-3, bz=MonkhorstPack(H, [1, 1000, 1]))
-    >>> rse.initialize()
+    >>> rse.setup(eta=1e-3, bz=MonkhorstPack(H, [1, 1000, 1]))
     >>> rse.green(0.1) # eta = 1e-3
     >>> rse.green(0.1 + 1j * 1e-4) # eta = 1e-4
 
@@ -736,8 +735,7 @@ def __init__(self, parent, semi_axis, k_axes, unfold=(1, 1, 1), **options):
             # The BrillouinZone used for integration
             "bz": None,
         }
-        self.set_options(**options)
-        self.initialize()
+        self.setup(**options)
 
     def __len__(self):
         r"""Dimension of the self-energy"""
@@ -763,7 +761,7 @@ def __str__(self):
     def set_options(self, **options):
         r"""Update options in the real-space self-energy
 
-        After updating options one should re-call `initialize` for consistency.
+        After updating options one should re-call `setup` for consistency.
 
         Parameters
         ----------
@@ -875,16 +873,30 @@ def real_space_coupling(self, ret_indices=False):
             return PC, atoms
         return PC
 
+    @deprecation(
+        "RealSpaceSE.initialize is deprecated in favor of RealSpaceSE.setup, please update code.",
+        "0.16.0",
+    )
     def initialize(self):
-        r"""Initialize the internal data-arrays used for efficient calculation of the real-space quantities
+        """See setup"""
+        self.setup()
+
+    def setup(self, **options):
+        r"""Setup the internal data-arrays used for efficient calculation of the real-space quantities
 
         This method should first be called *after* all options has been specified.
 
         If the user hasn't specified the ``bz`` value as an option this method will update the internal
         integration Brillouin zone based on ``dk`` and ``trs`` options. The :math:`\mathbf k` point sampling corresponds
         to the number of points in the non-folded system and thus the final sampling is equivalent to the
         sampling times the unfolding (per :math:`\mathbf k` direction).
+
+        See Also
+        --------
+        set_options : for argument details
         """
+        self.set_options(**options)
+
         s_ax = self._semi_axis
         k_ax = self._k_axes
 
@@ -1232,7 +1244,7 @@ def _func_bloch(k, dtype, no, tile, idx0):
         return G
 
     def clear(self):
-        """Clears the internal arrays created in `initialize`"""
+        """Clears the internal arrays created in `setup`"""
         del self._calc
 
 
@@ -1258,7 +1270,7 @@ class RealSpaceSI(SelfEnergy):
     surface : SparseOrbitalBZ
         parent object containing the surface of system. `semi` is attached into this
         object via the overlapping regions, the atoms that overlap `semi` and `surface`
-        are determined in the `initialize` routine.
+        are determined in the `setup` routine.
         `semi` and `surface` must have parallel lattice vectors.
     k_axes : array_like of int
         axes where k-points are desired. 1 or 2 values are required. The axis cannot be a direction
@@ -1299,8 +1311,7 @@ class RealSpaceSI(SelfEnergy):
     >>> Hsurf = H.tile(3, 0)
     >>> Hsurf.set_nsc(a=1)
     >>> rsi = RealSpaceSI(se, Hsurf, 1, (1, 4, 1))
-    >>> rsi.set_options(eta=1e-3, bz=MonkhorstPack(H, [1, 1000, 1]))
-    >>> rsi.initialize()
+    >>> rsi.setup(eta=1e-3, bz=MonkhorstPack(H, [1, 1000, 1]))
     >>> rsi.green(0.1) # eta = 1e-3
     >>> rsi.green(0.1 + 1j * 1e-4) # eta = 1e-4
 
@@ -1402,8 +1413,7 @@ def __init__(self, semi, surface, k_axes, unfold=(1, 1, 1), **options):
             # The BrillouinZone used for integration
             "bz": None,
         }
-        self.set_options(**options)
-        self.initialize()
+        self.setup(**options)
 
     def __len__(self):
         r"""Dimension of the self-energy"""
@@ -1432,7 +1442,7 @@ def __str__(self):
     def set_options(self, **options):
         r"""Update options in the real-space self-energy
 
-        After updating options one should re-call `initialize` for consistency.
+        After updating options one should re-call `setup` for consistency.
 
         Parameters
         ----------
@@ -1593,7 +1603,15 @@ def expand(atom, nrep, na, na_off):
             return PC, atom_idx
         return PC
 
+    @deprecation(
+        "RealSpaceSI.initialize is deprecated in favor of RealSpaceSI.setup, please update code.",
+        "0.16.0",
+    )
     def initialize(self):
+        """See setup"""
+        self.setup()
+
+    def setup(self, **options):
         r"""Initialize the internal data-arrays used for efficient calculation of the real-space quantities
 
         This method should first be called *after* all options has been specified.
@@ -1602,7 +1620,12 @@ def initialize(self):
         integration Brillouin zone based on the ``dk`` option. The :math:`\mathbf k` point sampling corresponds
         to the number of points in the non-folded system and thus the final sampling is equivalent to the
         sampling times the unfolding (per :math:`\mathbf k` direction).
+
+        See Also
+        --------
+        set_options : for argument details
         """
+        self.set_options(**options)
         P0 = self.real_space_parent()
 
         V_atoms = self.real_space_coupling(True)[1]
@@ -1863,5 +1886,5 @@ def _func_bloch(k, dtype, surf_orbs, semi_bulk):
         return G
 
     def clear(self):
-        """Clears the internal arrays created in `initialize`"""
+        """Clears the internal arrays created in `setup`"""
         del self._calc

src/sisl/physics/tests/test_self_energy.py

@@ -209,7 +209,7 @@ def test_real_space_HS(setup, k_axes, semi_axis, trs, bz, unfold):
         return
     RSE = RealSpaceSE(setup.HS, semi_axis, k_axes, (unfold, unfold, unfold))
     RSE.set_options(dk=100, trs=trs, bz=bz)
-    RSE.initialize()
+    RSE.setup()
     RSE.green(0.1)
 
 
@@ -236,7 +236,7 @@ def test_real_space_H_3d():
     H.construct(([0.001, 1.01], (0, -1)))
     RSE = RealSpaceSE(H, 0, [1, 2], (3, 4, 2))
     RSE.set_options(dk=100, trs=True)
-    RSE.initialize()
+    RSE.setup()
     nk = np.ones(3, np.int32)
     nk[[1, 2]] = 23
     bz = BrillouinZone(H, nk)
@@ -393,8 +393,7 @@ def test_real_space_SI_HS(setup, k_axes, trs, bz, unfold, bulk, coupling):
     surf = setup.HS.tile(4, 1)
     surf.set_nsc(b=1)
     RSI = RealSpaceSI(semi, surf, k_axes, (unfold, 1, unfold))
-    RSI.set_options(dk=100, trs=trs, bz=bz)
-    RSI.initialize()
+    RSI.setup(dk=100, trs=trs, bz=bz)
     RSI.self_energy(0.1, bulk=bulk, coupling=coupling)
 
 
@@ -414,7 +413,7 @@ def test_real_space_SI_H(
     surf.set_nsc(b=1)
     RSI = RealSpaceSI(semi, surf, k_axes, (unfold, 1, unfold))
     RSI.set_options(dk=100, trs=trs, bz=bz, semi_bulk=semi_bulk)
-    RSI.initialize()
+    RSI.setup()
     RSI.self_energy(0.1, bulk=bulk, coupling=coupling)
 
 
@@ -424,7 +423,7 @@ def test_real_space_SI_H_test(setup):
     surf.set_nsc(b=1)
     RSI = RealSpaceSI(semi, surf, 0, (3, 1, 3))
     RSI.set_options(dk=100, trs=False, bz=None)
-    RSI.initialize()
+    RSI.setup()
     RSI.green(0.1, [0, 0, 0.1], dtype=np.complex128)
     RSI.self_energy(0.1, [0, 0, 0.1])
     RSI.clear()
@@ -435,8 +434,7 @@ def test_real_space_SI_H_k_trs(setup):
     surf = setup.H.tile(4, 1)
     surf.set_nsc(b=1)
     RSI = RealSpaceSI(semi, surf, 0, (3, 1, 3))
-    RSI.set_options(dk=100, trs=True, bz=None)
-    RSI.initialize()
+    RSI.setup(dk=100, trs=True, bz=None)
     with pytest.raises(ValueError):
         RSI.green(0.1, [0, 0, 0.1], dtype=np.complex128)