fixed tests and docs

Signed-off-by: Nick Papior <[email protected]>

Author: zerothi

docs/api/default_geom.rst

@@ -14,6 +14,9 @@ geometries via a `pull request <pr>`_.
 
 All methods return a `Geometry` object.
 
+Some of the geometries are created in section based geometries, such as `heteroribbon`.
+This functionality is provided through the `composite_geometry`
+
 
 Bulk
 ====
@@ -51,6 +54,8 @@ Surfaces (slabs)
    zgnr
    graphene_nanoribbon
    nanotube
+   heteroribbon
+   graphene_heteroribbon
 
 
 2D materials
@@ -62,3 +67,12 @@ Surfaces (slabs)
    honeycomb
    bilayer
    graphene
+
+
+Helpers
+=======
+
+.. autosummary::
+   :toctree: generated/
+
+   composite_geometry

src/sisl/geom/__init__.py

@@ -42,6 +42,7 @@
    graphene
 
 """
+from ._composite import *
 from .basic import *
 from .bilayer import *
 from .category import *

src/sisl/geom/composite.py renamed to src/sisl/geom/_composite.py

@@ -1,11 +1,23 @@
 from dataclasses import dataclass, copy, fields 
+from abc import abstractmethod
 
-from sisl.messages import warn
+from sisl.messages import warn, SislError
+
+
+__all__ = ["composite_geometry"]
 
 
 @dataclass
 class _geom_section:
 
+    @abstractmethod
+    def build_section(self, geometry):
+        ...
+
+    @abstractmethod
+    def add_section(self, geometry, geometry_addition):
+        ...
+
     def _junction_error(self, prev, msg, what):
         """Helper function to raise an error if the junction is not valid.
 
@@ -14,7 +26,7 @@ def _junction_error(self, prev, msg, what):
         """
         msg = f"Error at junction between sections {prev} and {self}. {msg}"
         if what == "raise":
-            raise ValueError(msg)
+            raise SislError(msg)
         elif what == "warn":
             warn(msg)
 
@@ -29,8 +41,8 @@ def composite_geometry(sections, section_cls=_geom_section, **kwargs):
     sections: array-like of (_geom_section or tuple or dict)
         A list of sections to be added to the ribbon.
 
-        Each section is either a `_geom_section` or something that will
-        be parsed to a `_geom_section`.
+        Each section is either a `composite_geometry.section` or something that will
+        be parsed to a `composite_geometry.section`.
     section_cls: class, optional
         The class to use for parsing sections.
     **kwargs:
@@ -50,12 +62,12 @@ def conv(s):
 
         return copy.copy(s)
 
-    sections = [conv(section) for section in sections]
-    
     # Then loop through all the sections.
     geom = None
     prev = None
     for i, section in enumerate(sections):
+        section = conv(section)
+
         new_addition = section.build_section(prev)
 
         if i == 0:
@@ -66,3 +78,5 @@ def conv(s):
         prev = section
 
     return geom
+
+composite_geometry.section = _geom_section

src/sisl/geom/nanoribbon.py

@@ -7,14 +7,14 @@
 import numpy as np
 
 from sisl import Atom, geom
-from .composite import _geom_section, composite_geometry
+from ._composite import _geom_section, composite_geometry
 from sisl._internal import set_module
 
 from ._common import geometry_define_nsc
 
 __all__ = [
     'nanoribbon', 'graphene_nanoribbon', 'agnr', 'zgnr',
-    'heteroribbon', 'graphene_heteroribbon', '_heteroribbon_section'
+    'heteroribbon', 'graphene_heteroribbon',
 ]
 
 
@@ -165,6 +165,7 @@ def zgnr(width, bond=1.42, atoms=None):
     """
     return graphene_nanoribbon(width, bond, atoms, kind='zigzag')
 
+
 @set_module("sisl.geom")
 @dataclass
 class _heteroribbon_section(_geom_section):
@@ -582,14 +583,14 @@ def _parse_shift(self, shift, prev, align):
 def heteroribbon(sections, section_cls=_heteroribbon_section, **kwargs):
     """Build a nanoribbon consisting of several nanoribbons of different widths.
 
-    This function basically uses `composite_geometry`, but defaulting to the usage
-    of `_heteroribbon_section` as the section class.
+    This function uses `composite_geometry`, but defaulting to the usage
+    of `heteroribbon.section` as the section class.
 
-    See `heteroribbon_section` and `composite_geometry` for arguments.
+    See `heteroribbon.section` and `composite_geometry` for arguments.
 
     Returns
     -------
-    sisl.Geometry:
+    Geometry:
         The final structure of the heteroribbon.
 
     Notes
@@ -618,6 +619,8 @@ def heteroribbon(sections, section_cls=_heteroribbon_section, **kwargs):
     """
     return composite_geometry(sections, section_cls=section_cls, **kwargs)
 
+heteroribbon.section=_heteroribbon_section
+
 
 @set_module("sisl.geom")
 def graphene_heteroribbon(sections, section_cls=_heteroribbon_section, bond=1.42, atoms=None, **kwargs):
@@ -628,8 +631,10 @@ def graphene_heteroribbon(sections, section_cls=_heteroribbon_section, bond=1.42
 
     See also
     ----------
-    `heteroribbon` : for argument details and how it behaves
+    heteroribbon : for argument details and how it behaves
     """
     if atoms is None:
         atoms = Atom(Z=6, R=bond * 1.01)
     return composite_geometry(sections, section_cls=section_cls, bond=bond, atoms=atoms, **kwargs)
+
+graphene_heteroribbon.section=_heteroribbon_section

src/sisl/geom/tests/test_geom.py

@@ -9,7 +9,7 @@
 import math as m
 import numpy as np
 
-from sisl import Atom, Lattice
+from sisl import Atom, Lattice, SislError
 from sisl._math_small import cross3, dot3
 from sisl.geom import *
 
@@ -152,15 +152,15 @@ def test_graphene_heteroribbon():
 def test_graphene_heteroribbon_errors():
     # 7-open with 9 can only be perfectly aligned.
     graphene_heteroribbon([(7, 1), (9, 1)], align="center", on_lone_atom="raise")
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         graphene_heteroribbon([(7, 1), (9, 1, -1)], align="center", on_lone_atom="raise")
     # From the bottom
     graphene_heteroribbon([(7, 1), (9, 1, -1)], align="bottom", on_lone_atom="raise")
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         graphene_heteroribbon([(7, 1), (9, 1, 0)], align="bottom", on_lone_atom="raise")
     # And from the top
     graphene_heteroribbon([(7, 1), (9, 1, 1)], align="top", on_lone_atom="raise")
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         graphene_heteroribbon([(7, 1), (9, 1, -1)], align="top", on_lone_atom="raise")
 
 
@@ -169,16 +169,16 @@ def test_graphene_heteroribbon_errors():
     )
 
     # Odd section with open end
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         grap_heteroribbon([(7, 3), (5, 2)])
 
     # Shift limits are imposed correctly
     # In this case -2 < shift < 1
     grap_heteroribbon([(7, 3), (11, 2, 0)])
     grap_heteroribbon([(7, 3), (11, 2, -1)])
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         grap_heteroribbon([(7, 3), (11, 2, 1)])
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         grap_heteroribbon([(7, 3), (11, 2, -2)])
 
     # Periodic boundary conditions work properly
@@ -188,10 +188,10 @@ def test_graphene_heteroribbon_errors():
 
     # Even ribbons should only be shifted towards the center
     grap_heteroribbon([(10, 2), (8, 2, -1)])
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         grap_heteroribbon([(10, 2), (8, 2, 1)])
     grap_heteroribbon([(10, 1), (8, 2, 1)],) #pbc=False)
-    with pytest.raises(ValueError):
+    with pytest.raises(SislError):
         grap_heteroribbon([(10, 1), (8, 2, -1)],) #pbc=False)