Add PeriodicCollapser

src/stk/molecular/molecules/constructed_molecule.py

@@ -70,19 +70,10 @@ def __init__(self, topology_graph):
 
         """
 
-        construction_result = topology_graph.construct()
-        super().__init__(
-            atoms=construction_result.get_atoms(),
-            bonds=construction_result.get_bonds(),
-            position_matrix=construction_result.get_position_matrix(),
+        self._init_from_construction_result(
+            obj=self,
+            construction_result=topology_graph.construct(),
         )
-        self._atom_infos = construction_result.get_atom_infos()
-        self._bond_infos = construction_result.get_bond_infos()
-        self._num_building_blocks = {
-            building_block:
-                topology_graph.get_num_building_block(building_block)
-            for building_block in topology_graph.get_building_blocks()
-        }
 
     @classmethod
     def init(
@@ -132,6 +123,74 @@ def init(
         molecule._num_building_blocks = dict(num_building_blocks)
         return molecule
 
+    @classmethod
+    def init_from_construction_result(
+        cls,
+        construction_result,
+    ):
+        """
+        Initialize a :class:`.ConstructedMolecule`.
+
+        Parameters
+        ----------
+        construction_result : :class:`.ConstructionResult`
+            The result of a construction, from which the
+            :class:`.ConstructedMolecule` should be initialized.
+
+        Returns
+        -------
+        :class:`.ConstructedMolecule`
+            The constructed molecule.
+
+        """
+
+        return cls._init_from_construction_result(
+            obj=cls.__new__(cls),
+            construction_result=construction_result,
+        )
+
+    @staticmethod
+    def _init_from_construction_result(
+        obj,
+        construction_result,
+    ):
+        """
+        Initialize a :class:`.ConstructedMolecule`.
+
+        This modifies `obj`.
+
+        Parameters
+        ----------
+        obj : :class:`.ConstructedMolecule`
+            The constructed molecule to initialize.
+
+        construction_result : :class:`.ConstructionResult`
+            The result of a construction, from which the
+            :class:`.ConstructedMolecule` should be initialized.
+
+        Returns
+        -------
+        :class:`.ConstructedMolecule`
+            The `obj` instance.
+
+        """
+
+        super(ConstructedMolecule, obj).__init__(
+            atoms=construction_result.get_atoms(),
+            bonds=construction_result.get_bonds(),
+            position_matrix=construction_result.get_position_matrix(),
+        )
+        obj._atom_infos = construction_result.get_atom_infos()
+        obj._bond_infos = construction_result.get_bond_infos()
+        obj._num_building_blocks = {
+            building_block: construction_result.get_num_building_block(
+                building_block=building_block,
+            )
+            for building_block
+            in construction_result.get_building_blocks()
+        }
+        return obj
+
     def clone(self):
         clone = super().clone()
         clone._atom_infos = self._atom_infos

src/stk/molecular/topology_graphs/cof/cof.py

@@ -32,7 +32,12 @@
 from functools import partial
 from operator import getitem
 
-from ..topology_graph import TopologyGraph, NullOptimizer, EdgeGroup
+from ..topology_graph import (
+    TopologyGraph,
+    NullOptimizer,
+    EdgeGroup,
+    PeriodicConstructionResult,
+)
 from .vertices import _UnaligningVertex
 from .edge import _CofEdge
 from ...reactions import GenericReactionFactory
@@ -95,10 +100,12 @@ class Cof(TopologyGraph):
 
     For :class:`.Cof` topologies, it is recommend to use the
     :class:`.Collapser` optimizer if using the nonperiodic form.
-    However, no optimizer is valid for periodic systems currently.
+    For periodic systems, the :class:`.PeriodicCollapser` is
+    recommended.
 
     .. code-block:: python
 
+        # Nonperiodic.
         cof = stk.ConstructedMolecule(
             topology_graph=stk.cof.Honeycomb(
                 building_blocks=(bb1, bb2),
@@ -109,21 +116,33 @@ class Cof(TopologyGraph):
             ),
         )
 
-    *Accessing the Periodic Unit Cell*
+        # Periodic.
+        cof = stk.ConstructedMolecule(
+            topology_graph=stk.cof.PeriodicHoneycomb(
+                building_blocks=(bb1, bb2),
+                lattice_size=(3, 3, 1),
+                optimizer=stk.PeriodicCollapser(),
+            ),
+        )
 
-    The same :class:`.Cof` instance can be built as a periodic
-    structure, which has a unit cell (assuming as P1 space group) that
-    can be accessed at any time from the :class:`.TopologyGraph`
-    instance.
+    *Accessing the Periodic Information*
+
+    When building periodic :class:`.Cof` instances, the periodic
+    information, such as the unit cell, can be accessed if you use the
+    :class:`.PeriodicConstructionResult` returned by calling
+    :meth:`.Cof.construct`
 
     .. code-block:: python
 
         topology_graph = stk.cof.PeriodicHoneycomb(
             building_blocks=(bb1, bb2),
             lattice_size=(3, 3, 1),
         )
-        cof = stk.ConstructedMolecule(topology_graph)
-        periodic_info = topology.get_periodic_info()
+        construction_result = topology_graph.construct()
+        cof = stk.ConstructedMolecule.init_from_construction_result(
+            construction_result=construction_result,
+        )
+        periodic_info = construction_result.get_periodic_info()
         cell_matrix = periodic_info.get_cell_matrix()
         # Can access all unit-cell parameters.
         a = periodic_info.get_a()
@@ -132,6 +151,13 @@ class Cof(TopologyGraph):
         alpha = periodic_info.get_alpha()
         beta = periodic_info.get_beta()
         gamma = periodic_info.get_gamma()
+        # Write to .pdb file.
+        writer = stk.PdbWriter()
+        writer.write(
+            molecule=cof,
+            path='cof.pdb',
+            periodic_info=periodic_info,
+        )
 
     *Structural Isomer Construction*
 
@@ -663,6 +689,22 @@ def _get_building_block_vertices(
     def _get_lattice_constants(self):
         return self._lattice_constants
 
+    def construct(self):
+        """
+        Construct a :class:`.ConstructedMolecule`.
+
+        Returns
+        -------
+        :class:`.PeriodicConstructionResult`
+            The data describing the :class:`.ConstructedMolecule`.
+
+        """
+
+        return super().construct()
+
+    def _get_construction_result(self, state):
+        return PeriodicConstructionResult(state, self._lattice_size)
+
     def _get_scale(self, building_block_vertices):
         return 5*max(
             bb.get_maximum_diameter()

src/stk/molecular/topology_graphs/cof/periodic_hexagonal.py

@@ -5,6 +5,8 @@
 """
 
 import numpy as np
+import warnings
+
 from ...reactions import GenericReactionFactory
 from .cof import Cof
 from .vertices import _LinearCofVertex, _NonLinearCofVertex
@@ -28,8 +30,8 @@ class PeriodicHexagonal(Cof):
         | 6-functional groups: 0 to 3
         | 2-functional groups: 4 to 15
 
-    Note that :class:`.Optimizer` does not optimize the
-    :class:`.PeriodicInfo`.
+    Note that optimizers may not optimize the :class:`.PeriodicInfo`.
+    The documentation of the optimizer will state if it does.
 
     See :class:`.Cof` for more details and examples.
 
@@ -133,6 +135,15 @@ def get_periodic_info(self):
 
         """
 
+        warnings.warn(
+            'You called get_periodic_info() on a topology graph '
+            'instance. This method will be removed in any version '
+            'of stk released on, or after, 21/10/21. Please call '
+            'the construct() method instead. This will return a '
+            'PeriodicConstructionResult which provides the new '
+            'get_periodic_info() method.'
+        )
+
         lattice_constants = self._get_lattice_constants()
 
         return PeriodicInfo(

src/stk/molecular/topology_graphs/cof/periodic_honeycomb.py

@@ -5,6 +5,8 @@
 """
 
 import numpy as np
+import warnings
+
 from ...reactions import GenericReactionFactory
 from .cof import Cof
 from .vertices import _LinearCofVertex, _NonLinearCofVertex
@@ -28,8 +30,8 @@ class PeriodicHoneycomb(Cof):
         | 3-functional groups: 0 to 1
         | 2-functional groups: 2 to 4
 
-    Note that :class:`.Optimizer` does not optimize the
-    :class:`.PeriodicInfo`.
+    Note that optimizers may not optimize the :class:`.PeriodicInfo`.
+    The documentation of the optimizer will state if it does.
 
     See :class:`.Cof` for more details and examples.
 
@@ -133,6 +135,15 @@ def get_periodic_info(self):
 
         """
 
+        warnings.warn(
+            'You called get_periodic_info() on a topology graph '
+            'instance. This method will be removed in any version '
+            'of stk released on, or after, 21/10/21. Please call '
+            'the construct() method instead. This will return a '
+            'PeriodicConstructionResult which provides the new '
+            'get_periodic_info() method.'
+        )
+
         lattice_constants = self._get_lattice_constants()
 
         return PeriodicInfo(

src/stk/molecular/topology_graphs/cof/periodic_kagome.py

@@ -5,6 +5,8 @@
 """
 
 import numpy as np
+import warnings
+
 from ...reactions import GenericReactionFactory
 from .cof import Cof
 from .vertices import _LinearCofVertex, _NonLinearCofVertex
@@ -28,8 +30,8 @@ class PeriodicKagome(Cof):
         | 4-functional groups: 0 to 2
         | 2-functional groups: 3 to 8
 
-    Note that :class:`.Optimizer` does not optimize the
-    :class:`.PeriodicInfo`.
+    Note that optimizers may not optimize the :class:`.PeriodicInfo`.
+    The documentation of the optimizer will state if it does.
 
     See :class:`.Cof` for more details and examples.
 
@@ -133,6 +135,15 @@ def get_periodic_info(self):
 
         """
 
+        warnings.warn(
+            'You called get_periodic_info() on a topology graph '
+            'instance. This method will be removed in any version '
+            'of stk released on, or after, 21/10/21. Please call '
+            'the construct() method instead. This will return a '
+            'PeriodicConstructionResult which provides the new '
+            'get_periodic_info() method.'
+        )
+
         lattice_constants = self._get_lattice_constants()
 
         return PeriodicInfo(

src/stk/molecular/topology_graphs/cof/periodic_linkerless_honeycomb.py

@@ -5,6 +5,8 @@
 """
 
 import numpy as np
+import warnings
+
 from ...reactions import GenericReactionFactory
 from .cof import Cof
 from .vertices import _NonLinearCofVertex
@@ -27,8 +29,8 @@ class PeriodicLinkerlessHoneycomb(Cof):
 
         | 3-functional groups: 0 to 1
 
-    Note that :class:`.Optimizer` does not optimize the
-    :class:`.PeriodicInfo`.
+    Note that optimizers may not optimize the :class:`.PeriodicInfo`.
+    The documentation of the optimizer will state if it does.
 
     See :class:`.Cof` for more details and examples.
 
@@ -132,6 +134,15 @@ def get_periodic_info(self):
 
         """
 
+        warnings.warn(
+            'You called get_periodic_info() on a topology graph '
+            'instance. This method will be removed in any version '
+            'of stk released on, or after, 21/10/21. Please call '
+            'the construct() method instead. This will return a '
+            'PeriodicConstructionResult which provides the new '
+            'get_periodic_info() method.'
+        )
+
         lattice_constants = self._get_lattice_constants()
 
         return PeriodicInfo(

src/stk/molecular/topology_graphs/cof/periodic_square.py

@@ -5,6 +5,7 @@
 """
 
 import numpy as np
+import warnings
 from ...reactions import GenericReactionFactory
 from .cof import Cof
 from .vertices import _LinearCofVertex, _NonLinearCofVertex
@@ -28,8 +29,8 @@ class PeriodicSquare(Cof):
         | 4-functional groups: 0
         | 2-functional groups: 1 to 2
 
-    Note that :class:`.Optimizer` does not optimize the
-    :class:`.PeriodicInfo`.
+    Note that optimizers may not optimize the :class:`.PeriodicInfo`.
+    The documentation of the optimizer will state if it does.
 
     See :class:`.Cof` for more details and examples.
 
@@ -133,6 +134,15 @@ def get_periodic_info(self):
 
         """
 
+        warnings.warn(
+            'You called get_periodic_info() on a topology graph '
+            'instance. This method will be removed in any version '
+            'of stk released on, or after, 21/10/21. Please call '
+            'the construct() method instead. This will return a '
+            'PeriodicConstructionResult which provides the new '
+            'get_periodic_info() method.'
+        )
+
         lattice_constants = self._get_lattice_constants()
 
         return PeriodicInfo(

src/stk/molecular/topology_graphs/topology_graph/__init__.py

@@ -2,3 +2,4 @@
 from .vertex import *  # noqa
 from .topology_graph import *  # noqa
 from .optimizers import *  # noqa
+from .construction_result import *  # noqa

src/stk/molecular/topology_graphs/topology_graph/construction_result/__init__.py

@@ -0,0 +1,8 @@
+from .construction_result import ConstructionResult
+from .periodic import PeriodicConstructionResult
+
+
+__all__ = [
+    'ConstructionResult',
+    'PeriodicConstructionResult',
+]