added draw topology

Author: bafgreat

CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to `mofstructure` are recorded here. Versions follow the
 releases published on [PyPI](https://pypi.org/project/mofstructure/).
 
+## 0.1.9.0
+
+### Topology
+
+- Added a chemically explicit `ligand_cluster` representation in which complete
+  organic ligands and metal clusters are the two vertex classes. Edges record
+  distinct periodic ligand--cluster coordination incidences; multiple donor
+  bonds within one contact are consolidated without merging contacts to
+  different periodic images. Polytopic and ditopic ligands remain explicit
+  vertices. `collapse_ditopic=True` is available when a conventional contracted
+  RCSR net is required.
+- Made contracted nets invariant to atom ordering, cell origin and supercell
+  choice. Contact translations for periodic rods and sheets are now reduced
+  modulo the component translation lattice. This fixes order-dependent results
+  for MIL-53, whose `sbus` topology now remains `pcu` across equivalent input
+  representations.
+- Excluded singly coordinated dangling ligands, coordinated solvent and capping
+  modulators from the Systre net, preventing degree-one collisions from hiding
+  the underlying framework topology.
+- Made `topology_hash` independent of Systre's input-dependent node labels.
+  Existing hashes from earlier releases will not match the new values. Relaxed
+  coordinates may still differ by an ideal-space-group origin choice.
+
+### Descriptors
+
+- Added `MOFstructure.get_ligand_cluster_fingerprint()`. The fingerprint records
+  ligand and cluster species, periodic connectivity, denticity, terminal
+  ligands and refinement information without requiring Systre to identify the
+  net. Its normalized counts and `fingerprint_hash` are invariant to atom
+  ordering, cell origin and supercell expansion.
+
+### Visualization
+
+- Added `MOFstructure.draw_topology()` for interactive 3D inspection of the
+  extracted net over the framework geometry. It supports `sbus`, `all_node`,
+  `single_node` and `ligand_cluster`, periodic supercells, optional framework
+  and unit-cell layers, HTML export and static image export.
+- Corrected drawing across periodic boundaries by retaining graph translations,
+  self-edges and distinct periodic incidences. Every displayed connection ends
+  at a visible node image, and zero-length self-edges are removed.
+- Added a method-specific centre-to-centre view of SBU/metal and organic/linker
+  centres. Connections use solid green lines, while the abstract topology layer
+  can be enabled separately with `show_topology=True`.
+
+### Packaging and documentation
+
+- Added the optional `draw` extra for Plotly-based visualization and documented
+  the topology drawing and ligand--cluster fingerprint APIs.
+
 ## 0.1.8.9
 
 ### Topology

README.md

@@ -152,10 +152,45 @@ for a rod MOF like MIL-53, `all_node` gives `rna` and `single_node` gives `bpq`
 mofstructure_topology structure.cif --method all_node      # every branch point a node
 mofstructure_topology ./folder --method single_node        # organic groups merged
 mofstructure_topology ./folder --method sbus               # each SBU one node
-mofstructure_topology ./folder --method all                # all three, one record each
+mofstructure_topology ./folder --method ligand_cluster     # complete ligands and metal clusters
+mofstructure_topology ./folder --method all                # all methods, one record each
 ```
 
-Use `--method all` to compute all three at once. Each structure gets a single
+`ligand_cluster` constructs a bipartite incidence net from the same
+deconstruction as `get_ligands`, so its vertices are exactly the complete
+ligands and metal clusters that deconstruction returns and every atom belongs to
+one of them. An edge records coordination of a ligand to a particular periodic
+image of a cluster. Multiple donor bonds to the same cluster image count as one
+incidence, so chelation does not artificially increase the topological degree.
+
+A ditopic ligand stays a vertex, which subdivides the edge it makes, and RCSR
+lists no subdivided nets — UiO-66 comes back as `UNKNOWN` even though the net is
+right. That is deliberate: the point of this method is how the ligands meet the
+clusters, not the RCSR symbol, and the topology hash still identifies the net.
+Pass `collapse_ditopic=True` to `ligand_cluster_graph` or `cgd_ligand_cluster`
+to splice ditopic ligands into edges instead, which recovers the nameable net
+(`fcu` for UiO-66, `pcu` for MIL-53, `tbo` either way for HKUST-1).
+
+To ask what the ligands do rather than what the net is called, use the
+fingerprint, which is read straight from the deconstruction and needs no Systre:
+
+```python
+from mofstructure import structure
+
+mof = structure.MOFstructure(filename='UiO-66.cif')
+print(mof.get_ligand_cluster_fingerprint())
+```
+
+It counts each ligand and cluster species per metal-cluster unit, with how many
+clusters each ligand bridges and at what denticity, and it does not change when
+the atoms are listed in another order, when the cell origin moves, or when the
+same crystal is given as a supercell. That makes it sensitive to defects: a
+missing linker lowers a cluster's connectivity, a linker hanging by one end is
+listed under `terminal` with its own formula (which is what tells it apart from
+a coordinated solvent), and a carboxylate that has dropped from bridging to
+monodentate shows in the denticity histogram even though the net is unchanged.
+
+Use `--method all` to compute every method at once. Each structure gets a single
 record holding every net — nested under a `topologies` key in the JSON, and one
 column group per method in the CSV — so the output drops straight into a
 database:
@@ -264,6 +299,30 @@ identify_topology('UiO-66.cif', method='all_node')   # from a structure file
 identify_topology(read('UiO-66.cif'))                # from ASE atoms
 ```
 
+### Drawing the net
+
+`draw_topology` traces the net over the real framework and returns an
+interactive plotly figure — nodes at the real building-unit positions, edges
+following the connectivity. Needs the optional `plotly` extra
+(`pip install mofstructure[draw]`).
+
+```python
+fig = mof.draw_topology(method='all_node', filename='net.html')
+fig.show()   # or open net.html in a browser
+```
+
+The interactive, axis-free molecular view overlays the underlying net on the
+framework and shows the unit-cell boundary. Every connection ends at a visible
+centre, including connections to neighbouring periodic images. The default
+green centre-to-centre network is generated by the selected topology method,
+so its nodes and contractions visibly change between `sbus`, `all_node`,
+`single_node` and `ligand_cluster`. Framework atoms, framework bonds and each
+centre class can be toggled independently in the legend. The view shows this
+method-specific network by default;
+set `show_topology=True` to add the abstract blue topology edges and topology
+node markers. Set `show_linker_sbu=False`,
+`show_structure=False` or `show_unit_cell=False` to hide individual layers.
+
 ### Open metal sites
 
 ```python

docs/source/examples.rst

@@ -129,6 +129,33 @@ Available methods:
 - all_node: rod SBUs split into their atoms (CrystalNets AllNodes)
 - single_node: all_node with organic groups merged (CrystalNets SingleNodes)
 - sbus: each SBU as one node
+- ligand_cluster: complete organic ligands and metal clusters as the two vertex
+  classes of a coordination-incidence net
+
+In ``ligand_cluster``, a ligand remains a vertex even when it is ditopic.
+Several donor bonds from one ligand to the same periodic image of a metal
+cluster form one incidence, while connections to different cluster images
+remain distinct. Keeping ditopic ligands means the net is a subdivided one,
+which RCSR does not list, so frameworks such as UiO-66 report ``UNKNOWN`` with
+the topology hash still identifying the net. Pass ``collapse_ditopic=True`` to
+``ligand_cluster_graph`` or ``cgd_ligand_cluster`` to splice those ligands into
+edges and recover the nameable net.
+
+To describe how ligands meet clusters without going through Systre:
+
+.. code-block:: python
+
+   fingerprint = mof.get_ligand_cluster_fingerprint()
+   print(fingerprint["ligands"])   # {'C8H4O4': {'count': '6', 'contacts': {2: '6'}, ...}}
+   print(fingerprint["terminal"])  # coordinated solvent and dangling linkers
+   print(fingerprint["fingerprint_hash"])
+
+Counts are quoted per metal-cluster repeat unit as exact fractions, so the
+fingerprint is unchanged by atom ordering, by the cell origin, and by being
+given a supercell, while defects do move it: a missing linker lowers a
+cluster's connectivity, a linker bound at only one end appears under
+``terminal`` with its own formula, and a carboxylate reduced from bridging to
+monodentate appears in the denticity histogram.
 
 The output includes:
 - RCSR topology name
@@ -138,6 +165,26 @@ The output includes:
 - Topology hash for uniqueness
 - systre optimised cgd string representation
 
+Drawing the net
+---------------
+
+``draw_topology`` traces the net over the real framework and returns an
+interactive plotly figure. It needs the optional ``plotly`` extra
+(``pip install mofstructure[draw]``).
+
+.. code-block:: python
+
+   fig = mof.draw_topology(method="all_node", filename="net.html")
+
+The drawing preserves the lattice translation of every periodic edge, including
+self-edges of rod and sheet nodes. Framework atoms and bonds and the unit-cell
+boundary are displayed behind the net and can be hidden from the legend. Pass
+``show_structure=False`` or ``show_unit_cell=False`` for a net-only figure.
+An independent mapping layer displays complete linker centres, SBU centres and
+their coordination incidences for every topology method, including ``sbus``.
+Pass ``show_linker_sbu=False`` to hide this chemical mapping.
+   fig.show()
+
 Porosity Analysis
 =================
 Porosity properties are computed using our python wrapper around Zeo++ called pyzeo.

docs/source/updates.rst

@@ -1,3 +1,54 @@
+Updates Version 0.1.9.0
+=======================
+
+This release adds a chemically explicit ligand--cluster topology, stable
+framework fingerprints and interactive topology drawings. It also makes
+periodic contracted nets reproducible across equivalent structure files.
+
+Topology and fingerprints
+-------------------------
+
+``method="ligand_cluster"`` now constructs a periodic incidence graph whose two
+vertex classes are complete organic ligands and metal clusters. Every edge is a
+distinct periodic coordination incidence. Multiple donor bonds within one
+ligand--cluster contact are consolidated, while contacts to different periodic
+images remain separate. Ditopic and polytopic ligands stay explicit; use
+``collapse_ditopic=True`` when the conventional contracted RCSR net is needed.
+
+Translations for periodic rod and sheet clusters are reduced modulo the
+component translation lattice. Consequently, contracted topologies no longer
+depend on atom ordering, cell origin or whether the input is a primitive cell
+or supercell. Singly coordinated solvent, modulators and dangling ligands are
+excluded from the Systre net so degree-one collisions do not hide the framework
+topology.
+
+``MOFstructure.get_ligand_cluster_fingerprint()`` reports ligand and cluster
+species, connectivity, denticity, terminal ligands and refinement information
+without requiring an RCSR match. Its normalized counts and
+``fingerprint_hash`` are stable across atom ordering, origin shifts and
+supercell expansion.
+
+``topology_hash`` no longer includes Systre's input-dependent node labels.
+Hashes stored by previous versions will therefore not match values generated by
+0.1.9.0. Relaxed coordinates can still differ by the origin selected for the
+ideal space group.
+
+Topology visualization
+----------------------
+
+``MOFstructure.draw_topology()`` provides an interactive 3D view for ``sbus``,
+``all_node``, ``single_node`` and ``ligand_cluster``. Nodes are placed at their
+real building-unit centres, connections retain their periodic translations and
+optional framework and unit-cell layers show how the net maps onto the crystal.
+The method-specific centre-to-centre layer distinguishes SBU/metal centres from
+organic/linker centres; the abstract topology can be added with
+``show_topology=True``. Figures can be saved as interactive HTML or static
+images using the ``draw`` extra.
+
+Periodic self-edges and distinct incidences are now preserved in drawings,
+zero-length self-edges are removed, and every displayed connection terminates
+at a visible periodic node image.
+
 Updates Version 0.1.8.9
 =======================