Fixes (#517)

README.rst

@@ -43,6 +43,26 @@ on GitHub, and you can update your ``stk`` with::
 
     $ pip install stk --upgrade
 
+Developer Setup
+---------------
+
+#. Install `just`_.
+#. In a new virtual environment run::
+
+  $ just dev
+
+#. Setup the `MongoDB`_ container (make sure ``docker`` is installed)::
+
+  $ just mongo
+
+#. Run code checks::
+
+  $ just check
+
+
+.. _`just`: https://github.com/casey/just
+.. _`MongoDB`: https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
+
 How To Cite
 ===========
 
@@ -79,6 +99,10 @@ __ https://chemrxiv.org/articles/STK_A_Python_Toolkit_for_Supramolecular_Assembl
 using stk
 ---------
 
+* Using stk for constructing larger numbers of coarse-grained models: `Systematic exploration of accessible topologies of cage molecules via minimalistic models`__
+
+__ https://pubs.rsc.org/en/content/articlelanding/2023/sc/d3sc03991a
+
 * `The effect of disorder in multi-component covalent organic frameworks`__
 
 __ https://pubs.rsc.org/en/content/articlehtml/2023/cc/d3cc01111a

docs/source/basic_examples.rst

@@ -1176,8 +1176,8 @@ in this way, and you can mix different types of
 a :mod:`~.functional_groups.functional_group` instances with
 :mod:`~.functional_group_factory` instances.
 
-Changing Bonder and Deleter Atoms in Functional Group Factories
-===============================================================
+Changing Bonder, Placer and Deleter Atoms in Functional Group Factories
+=======================================================================
 
 In the previous example, you saw that during creation of a
 :class:`.Bromo` instance, you can specify which atoms have bonds
@@ -1270,6 +1270,29 @@ other :mod:`~.functional_group_factory`. Note that the number you
 provide to the factory, is not the id of the atom found in the
 molecule!!
 
+Finally, each :mod:`~.functional_group_factory` allows for the user to
+provide the placer ids, which tell :mod:`stk` which atoms in a functional
+group should be used for aligning and placing the molecule during
+construction. In most cases, this is not an important parameter and the
+default behaviour (where placers and bonders are equivalent) is
+appropropriate. However, in cases where your building block is small,
+you may get `NAN` or `division by zero` errors due to the vectors in a
+building block overlapping. If this occurs, we recommend using bonder
+and deleter atoms as placers like so:
+
+.. testcode:: changing-bonder-and-deleter-atoms-in-fg-factories
+
+    bb2 = stk.BuildingBlock(
+        smiles='C(Br)(Br)Br',
+        functional_groups=stk.BromoFactory(
+            # Defaults.
+            bonders=(0,),
+            deleters=(1,),
+            # Include both atoms.
+            placers=(0, 1)
+        ),
+    )
+
 Handling Molecules with Metal Atoms and Dative Bonds
 ====================================================
 

docs/source/graph_components.rst

@@ -0,0 +1,10 @@
+Topology Graph Components
+=========================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    TopologyGraph <_autosummary/stk.TopologyGraph>
+    Vertex <_autosummary/stk.Vertex>
+    Edge <_autosummary/stk.Edge>

docs/source/host_guest.rst

@@ -0,0 +1,9 @@
+Host Guest Complexes
+====================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    Complex <_autosummary/stk.host_guest.Complex>
+    Guest <_autosummary/stk.host_guest.Guest>

docs/source/index.rst

@@ -31,12 +31,13 @@
    :caption: Topology Graphs
    :maxdepth: 2
 
+   Topology Graph Components <graph_components>
    Polymers <polymer>
    Small Molecules <small>
    Organic & Metal-Organic Cages <cage>
    Covalent Organic Frameworks <cof>
    Metal Complexes <metal_complex>
-   Host Guest Complex <_autosummary/stk.host_guest.Complex>
+   Host Guest Complex <host_guest>
    Macrocycle <_autosummary/stk.macrocycle.Macrocycle>
    [n]Rotaxane <_autosummary/stk.rotaxane.NRotaxane>
    Adding Topology Graphs <_autosummary/stk.TopologyGraph>
@@ -89,6 +90,29 @@ To get :mod:`.stk`, you can install it with pip::
 
   $ pip install stk
 
+Installing a development enviromnent is easy too:
+
+#. Use a new Python 3.11 environment through `conda`_ or `mamba`_.
+#. Install `just`_.
+#. Clone the :mod:`.stk` repository.
+#. Setup development enviromnent::
+
+   $ just dev
+
+#. Setup the `MongoDB`_ container (make sure `docker` is installed)::
+
+   $ just mongo
+
+#. Test installation (running `black`, `mypy`, `pytest` and tests `make` on the docs)::
+
+   $ just check
+
+.. _`mamba`: https://mamba.readthedocs.io/en/latest/mamba-installation.html#mamba-install
+.. _`conda`: https://docs.conda.io/en/latest/
+.. _`just`: https://github.com/casey/just
+.. _`MongoDB`: https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
+
+
 Overview
 --------
 

docs/source/video_tutorials.rst

@@ -83,3 +83,26 @@ __ https://www.youtube.com/watch?v=1BBhPeIRV_E&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc
 __ https://github.com/andrewtarzia/SpinDry
 __ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
 
+
+Swapping Hosts and Guests in Complexes
+--------------------------------------
+
+`The new video`__ shows an example of loading an existing host-guest
+complex into :mod:`.stk`, extracting the different molecules
+(with :mod:`networkx`), and then building new complexes from that.
+The code is available here__.
+
+__ https://youtu.be/J29eoc9CZ98?si=vOEH45GPp_W0f5k4
+__ https://github.com/andrewtarzia/stk-examples/blob/main/replace_guest/replace_guest.py
+
+
+Processing *stk* building blocks before construction
+----------------------------------------------------
+
+`This video`__ shows the use of the new :mod:`bbprepared` library__
+that helps to process automatically generated :mod:`stk` BuildingBlock
+conformers to be better fit for construction.
+
+__ https://youtu.be/dbQwhlpf5Jc?si=7l9Y_ISEmFlY2FtV
+__ https://github.com/andrewtarzia/bbprepared
+

src/stk/_internal/building_block.py

@@ -399,7 +399,7 @@ def init(
     @classmethod
     def init_from_file(
         cls,
-        path: str,
+        path: pathlib.Path | str,
         functional_groups: FunctionalGroup
         | FunctionalGroupFactory
         | Iterable[FunctionalGroup | FunctionalGroupFactory] = (),
@@ -467,7 +467,7 @@ def init_from_file(
         # with rdkit often have issues, because rdkit tries to do
         # bits of structural analysis like stereocenters. Remake
         # gets rid of all this problematic metadata.
-        molecule = remake(cls._init_funcs[extension](path))
+        molecule = remake(cls._init_funcs[extension](str(path)))
 
         return cls.init_from_rdkit_mol(
             molecule=molecule,
@@ -1104,7 +1104,7 @@ def with_rotation_to_minimize_angle(
 
     def with_structure_from_file(
         self,
-        path: str,
+        path: pathlib.Path | str,
         extension: str | None = None,
     ) -> typing.Self:
         """
@@ -1133,7 +1133,7 @@ def with_structure_from_file(
             BuildingBlock: A clone with atomic positions found in `path`.
 
         """
-        return super().with_structure_from_file(path, extension)
+        return super().with_structure_from_file(str(path), extension)
 
     def write(
         self,

src/stk/_internal/constructed_molecule.py

@@ -571,7 +571,7 @@ def with_rotation_to_minimize_angle(
 
     def with_structure_from_file(
         self,
-        path: str,
+        path: pathlib.Path | str,
         extension: str | None = None,
     ) -> typing.Self:
         """
@@ -599,7 +599,7 @@ def with_structure_from_file(
 
             ConstructedMolecule: A clone with atomic positions found in `path`.
         """
-        return super().with_structure_from_file(path, extension)
+        return super().with_structure_from_file(str(path), extension)
 
     def write(
         self,

src/stk/_internal/ea/plotters/selection.py

@@ -233,7 +233,7 @@ def _plot(self, population: dict[T, float], counter: Counter) -> None:
             hue="heat_map",
             palette="magma_r",
             data=df,
-            s=[200 for _ in range(len(counter.keys()))],
+            size=[200 for _ in range(len(counter.keys()))],
             ax=ax,
         )
         ax.get_legend().remove()

src/stk/_internal/molecule.py

@@ -762,7 +762,7 @@ def to_rdkit_mol(self) -> rdkit.Mol:
 
     def with_structure_from_file(
         self,
-        path: str,
+        path: pathlib.Path | str,
         extension: str | None = None,
     ) -> typing.Self:
         """
@@ -802,7 +802,7 @@ def with_structure_from_file(
             ".xyz": xyz._with_structure_from_xyz,
             ".coord": turbomole._with_structure_from_turbomole,
             ".pdb": pdb._with_structure_from_pdb,
-        }[extension](self.clone(), path)
+        }[extension](self.clone(), str(path))
 
     def with_canonical_atom_ordering(self) -> typing.Self:
         """

src/stk/_internal/topology_graphs/cage/cage.py

@@ -973,6 +973,7 @@ def __init__(
         reaction_factory: ReactionFactory = GenericReactionFactory(),
         num_processes: int = 1,
         optimizer: Optimizer = NullOptimizer(),
+        scale_multiplier: float = 1.0,
     ) -> None:
         """
         Parameters:
@@ -1027,6 +1028,9 @@ def __init__(
                 Used to optimize the structure of the constructed
                 molecule.
 
+            scale_multiplier:
+                Scales the positions of the vertices.
+
         Raises:
 
             :class:`AssertionError`
@@ -1065,6 +1069,7 @@ def __init__(
         building_block_vertices = self._with_positioned_vertices(
             building_block_vertices=building_block_vertices,
             vertex_positions=self._vertex_positions,
+            scale_multiplier=scale_multiplier,
         )
         building_block_vertices = self._assign_aligners(
             building_block_vertices=building_block_vertices,
@@ -1081,6 +1086,7 @@ def __init__(
                 },
             )
         )
+
         super().__init__(
             building_block_vertices=typing.cast(
                 dict[BuildingBlock, abc.Sequence[Vertex]],
@@ -1095,6 +1101,7 @@ def __init__(
             num_processes=num_processes,
             optimizer=optimizer,
             edge_groups=None,
+            scale_multiplier=scale_multiplier,
         )
 
     def _with_positioned_vertices(
@@ -1103,14 +1110,16 @@ def _with_positioned_vertices(
             BuildingBlock, abc.Sequence[_CageVertex]
         ],
         vertex_positions: dict[int, np.ndarray],
+        scale_multiplier: float,
     ) -> dict[BuildingBlock, abc.Sequence[_CageVertex]]:
         clone = dict(building_block_vertices)
         for building_block, vertices in clone.items():
             new_vertices = []
             for vertex in vertices:
                 if vertex.get_id() in self._vertex_positions:
                     scale = self._get_scale(
-                        building_block_vertices  # type: ignore
+                        building_block_vertices,  # type: ignore
+                        scale_multiplier=scale_multiplier,
                     )
                     # Pre-reversing the scale
                     # because altering the scale code is topology level,
@@ -1151,7 +1160,7 @@ def _normalize_edge_prototypes(
     @classmethod
     def _normalize_building_blocks(
         cls,
-        building_blocks: typing.Iterable[BuildingBlock]
+        building_blocks: abc.Iterable[BuildingBlock]
         | dict[
             BuildingBlock,
             tuple[int, ...],
@@ -1261,7 +1270,7 @@ def clone(self) -> typing.Self:
     @classmethod
     def _get_vertices(
         cls,
-        vertex_ids: int | typing.Iterable[int],
+        vertex_ids: int | abc.Iterable[int],
     ) -> typing.Iterator[_CageVertex]:
         """
         Yield vertex prototypes.
@@ -1310,7 +1319,7 @@ def _has_degree(
     @classmethod
     def _get_building_block_vertices(
         cls,
-        building_blocks: typing.Iterable[BuildingBlock],
+        building_blocks: abc.Iterable[BuildingBlock],
     ) -> dict[BuildingBlock, abc.Sequence[_CageVertex]]:
         """
         Map building blocks to the vertices of the graph.
@@ -1375,11 +1384,14 @@ def _get_building_block_vertices(
             building_block_vertices,
         )
 
+    @staticmethod
     def _get_scale(
-        self,
         building_block_vertices: dict[BuildingBlock, abc.Sequence[Vertex]],
+        scale_multiplier: float,
     ) -> float:
-        return max(bb.get_maximum_diameter() for bb in building_block_vertices)
+        return scale_multiplier * max(
+            bb.get_maximum_diameter() for bb in building_block_vertices
+        )
 
     def _get_construction_state(self) -> _CageConstructionState:
         return _CageConstructionState(

src/stk/_internal/topology_graphs/cage/m3l3_triangle.py

@@ -154,6 +154,7 @@ def __init__(
         reaction_factory: ReactionFactory = GenericReactionFactory(),
         num_processes: int = 1,
         optimizer: Optimizer = NullOptimizer(),
+        scale_multiplier: float = 1.0,
     ) -> None:
         """
         Parameters:
@@ -214,6 +215,9 @@ def __init__(
                 Used to optimize the structure of the constructed
                 molecule.
 
+            scale_multiplier:
+                Scales the positions of the vertices.
+
         Raises:
 
             :class:`AssertionError`
@@ -259,6 +263,7 @@ def __init__(
             reaction_factory=reaction_factory,
             num_processes=num_processes,
             optimizer=optimizer,
+            scale_multiplier=scale_multiplier,
         )
 
     _x = 2 * np.sqrt(3) / 4