netsunhinged 0.1.0__tar.gz

netsunhinged-0.1.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use NetsUnhinged, please cite it as below, together with the method paper by Sarkisov et al."
+title: "NetsUnhinged: rigid-body / hinge flexibility analysis of framework materials"
+type: software
+authors:
+  - family-names: "Weiss"
+    given-names: "Jan-Benedikt"
+    affiliation: "TU Dortmund University"
+    # orcid: "https://orcid.org/0000-0000-0000-0000"
+license: MIT
+version: 0.1.0
+date-released: "2026-10-23"
+repository-code: "https://github.com/JBWeiss-chem/netsunhinged"
+keywords:
+  - metal-organic frameworks
+  - zeolites
+  - flexibility
+  - rigidity
+  - crystallography
+references:
+  - type: article
+    title: "On the Flexibility of Metal–Organic Frameworks"
+    authors:
+      - family-names: "Sarkisov"
+        given-names: "Lev"
+      - family-names: "Martin"
+        given-names: "Richard L."
+      - family-names: "Haranczyk"
+        given-names: "Maciej"
+      - family-names: "Smit"
+        given-names: "Berend"
+    journal: "Journal of the American Chemical Society"
+    year: 2014
+    volume: 136
+    start: 2228
+    doi: "10.1021/ja411673b"

netsunhinged-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Jan-Benedikt Weiss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---------------------------------------------------------------------------------
+Third-party components
+
+* three.js (netsunhinged/static/vendor/three/): MIT License, Copyright 2010-2023
+  three.js authors. See netsunhinged/static/vendor/three/LICENSE.
+* Example structures (netsunhinged/examples/): from the Crystallography Open
+  Database, dedicated to the public domain (CC0). See
+  netsunhinged/examples/README.md for the original publications.

netsunhinged-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+# extra files for the source distribution (the wheel only contains the package)
+include CITATION.cff
+include tests/*.py

netsunhinged-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: netsunhinged
+Version: 0.1.0
+Summary: Is your net unhinged? Rigid-body / hinge flexibility analysis of framework materials (MOFs, ZIFs, zeolites)
+Author: Jan-Benedikt Weiss
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JBWeiss-chem/netsunhinged
+Project-URL: Issues, https://github.com/JBWeiss-chem/netsunhinged/issues
+Keywords: metal-organic frameworks,MOF,zeolites,flexibility,rigidity,crystallography,CIF
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: netsunhinged/static/vendor/three/LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: server
+Requires-Dist: gunicorn>=22; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# NetsUnhinged
+
+A vibe-coded web app that predicts whether a framework material (MOFs, ZIFs, zeolites and other nets)
+is **potentially flexible** by treating it as a periodic network of rigid bodies joined by hinges
+and pivots. It implements and generalises
+
+> L. Sarkisov, R. L. Martin, M. Haranczyk, B. Smit, *On the Flexibility of Metal–Organic
+> Frameworks*, J. Am. Chem. Soc. **2014**, 136, 2228, [doi:10.1021/ja411673b](https://doi.org/10.1021/ja411673b).
+
+What it does:
+
+* reads a CIF (symmetry expansion, removal of guests, H and other dangling atoms),
+* shows the structure in 3D, coloured by element, rigid body, or degrees of freedom,
+* lets you **click atoms and bonds to choose what is flexible**,
+* analyses the resulting mechanism twice: once infinitesimally (exact linear algebra) and once with the
+  paper's finite deformation test (13 cell-perturbation regimes).
+
+## Installation
+
+NetsUnhinged needs Python ≥ 3.10 and installs `numpy` and `scipy`. three.js (0.160.0, MIT licence)
+is bundled, so the viewer works offline and makes no third-party requests.
+
+NetsUnhinged is on [PyPI](https://pypi.org/project/netsunhinged/).
+
+**Without Python, with uv (simplest).** [uv](https://docs.astral.sh/uv/) downloads Python by
+itself. Install uv once (macOS / Linux):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+or on Windows (PowerShell):
+
+```bash
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then start the app at any time with:
+
+```bash
+uvx netsunhinged
+```
+
+or install the `netsunhinged` command permanently with `uv tool install netsunhinged`. If the
+command is not found afterwards, run `uv tool update-shell` and open a new terminal.
+
+**With pipx.** [pipx](https://pipx.pypa.io) installs the app in its own environment and puts the
+`netsunhinged` command on your PATH:
+
+```bash
+pipx install netsunhinged
+```
+
+**With pip**, ideally inside a virtual environment or conda environment:
+
+```bash
+pip install netsunhinged
+```
+
+**With Docker** (then open http://localhost:8765):
+
+```bash
+docker run --rm -p 8765:8765 ghcr.io/jbweiss-chem/netsunhinged
+```
+
+**The latest development version** from GitHub:
+
+```bash
+pipx install git+https://github.com/JBWeiss-chem/netsunhinged
+```
+
+To update: `uv tool upgrade netsunhinged`, `pipx upgrade netsunhinged`, `pip install --upgrade
+netsunhinged` or `docker pull` the image. `uvx` reuses the version it downloaded first; run
+`uvx netsunhinged@latest` to get the newest release.
+
+## Usage
+
+After installing, start the app with:
+
+```bash
+netsunhinged
+```
+
+Your browser opens the app at http://127.0.0.1:8765. It runs only on your computer: nothing is
+uploaded anywhere. Stop it with Ctrl+C in the terminal. `netsunhinged serve` does the same and takes
+options: `--port 9000` uses another port, `--no-browser` does not open a browser window.
+
+If the command is not found (e.g. because the environment you installed it into is not active), use
+`python -m netsunhinged` instead.
+
+Analyse CIF files from the command line:
+
+```bash
+netsunhinged analyze my.cif other.cif --preset paper
+```
+
+`netsunhinged analyze --help` lists all options. `python -m netsunhinged` works as well.
+
+The **Examples** menu lists the literature structures in `netsunhinged/examples/`: open-licence (CC0)
+copies from the Crystallography Open Database, named `{trivial name}_COD-{id}.cif` (see
+`netsunhinged/examples/README.md`). In a source checkout, files in `examples_local/` (e.g. CSD
+downloads, which may not be redistributed) appear locally as "Local only" and are never published.
+
+## Limitations
+
+* This is a screening tool. As the paper notes, it finds *potential* modes. Energetics, sterics and
+  guest effects need force-field or DFT follow-up.
+* The model is all-or-nothing: an angle or torsion is either fixed or completely free. A mechanism
+  or a "flexible" regime therefore means that the deformation is possible without distorting any
+  rigid body, not that it costs no energy. In the material, the released angles and torsions,
+  non-bonded interactions and guests still resist it. The reported E and F measure the geometric
+  mismatch at the joints (Ų), not an energy.
+* Bodies are geometric: atoms have no size, so very large deformations can pass through each other.
+  Inspect the deformed frames.
+* Bonds come from covalent radii (+0.45 Å). Only the first disorder component is kept, and partially
+  occupied sites are kept as full atoms.
+* Frameworks with fewer than 3 periodic dimensions (layers, chains) have no bonds, and so no
+  constraints, in the remaining directions. The model reports them as flexible there, although
+  interlayer or interchain interactions may hold them in place. A warning is shown.
+
+## License
+
+MIT, see `LICENSE`. The bundled three.js is MIT-licensed as well. The example structures come from
+the Crystallography Open Database and are in the public domain (CC0); please cite the original
+publications listed in `netsunhinged/examples/README.md`.

netsunhinged-0.1.0/README.md

@@ -0,0 +1,125 @@
+# NetsUnhinged
+
+A vibe-coded web app that predicts whether a framework material (MOFs, ZIFs, zeolites and other nets)
+is **potentially flexible** by treating it as a periodic network of rigid bodies joined by hinges
+and pivots. It implements and generalises
+
+> L. Sarkisov, R. L. Martin, M. Haranczyk, B. Smit, *On the Flexibility of Metal–Organic
+> Frameworks*, J. Am. Chem. Soc. **2014**, 136, 2228, [doi:10.1021/ja411673b](https://doi.org/10.1021/ja411673b).
+
+What it does:
+
+* reads a CIF (symmetry expansion, removal of guests, H and other dangling atoms),
+* shows the structure in 3D, coloured by element, rigid body, or degrees of freedom,
+* lets you **click atoms and bonds to choose what is flexible**,
+* analyses the resulting mechanism twice: once infinitesimally (exact linear algebra) and once with the
+  paper's finite deformation test (13 cell-perturbation regimes).
+
+## Installation
+
+NetsUnhinged needs Python ≥ 3.10 and installs `numpy` and `scipy`. three.js (0.160.0, MIT licence)
+is bundled, so the viewer works offline and makes no third-party requests.
+
+NetsUnhinged is on [PyPI](https://pypi.org/project/netsunhinged/).
+
+**Without Python, with uv (simplest).** [uv](https://docs.astral.sh/uv/) downloads Python by
+itself. Install uv once (macOS / Linux):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+or on Windows (PowerShell):
+
+```bash
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then start the app at any time with:
+
+```bash
+uvx netsunhinged
+```
+
+or install the `netsunhinged` command permanently with `uv tool install netsunhinged`. If the
+command is not found afterwards, run `uv tool update-shell` and open a new terminal.
+
+**With pipx.** [pipx](https://pipx.pypa.io) installs the app in its own environment and puts the
+`netsunhinged` command on your PATH:
+
+```bash
+pipx install netsunhinged
+```
+
+**With pip**, ideally inside a virtual environment or conda environment:
+
+```bash
+pip install netsunhinged
+```
+
+**With Docker** (then open http://localhost:8765):
+
+```bash
+docker run --rm -p 8765:8765 ghcr.io/jbweiss-chem/netsunhinged
+```
+
+**The latest development version** from GitHub:
+
+```bash
+pipx install git+https://github.com/JBWeiss-chem/netsunhinged
+```
+
+To update: `uv tool upgrade netsunhinged`, `pipx upgrade netsunhinged`, `pip install --upgrade
+netsunhinged` or `docker pull` the image. `uvx` reuses the version it downloaded first; run
+`uvx netsunhinged@latest` to get the newest release.
+
+## Usage
+
+After installing, start the app with:
+
+```bash
+netsunhinged
+```
+
+Your browser opens the app at http://127.0.0.1:8765. It runs only on your computer: nothing is
+uploaded anywhere. Stop it with Ctrl+C in the terminal. `netsunhinged serve` does the same and takes
+options: `--port 9000` uses another port, `--no-browser` does not open a browser window.
+
+If the command is not found (e.g. because the environment you installed it into is not active), use
+`python -m netsunhinged` instead.
+
+Analyse CIF files from the command line:
+
+```bash
+netsunhinged analyze my.cif other.cif --preset paper
+```
+
+`netsunhinged analyze --help` lists all options. `python -m netsunhinged` works as well.
+
+The **Examples** menu lists the literature structures in `netsunhinged/examples/`: open-licence (CC0)
+copies from the Crystallography Open Database, named `{trivial name}_COD-{id}.cif` (see
+`netsunhinged/examples/README.md`). In a source checkout, files in `examples_local/` (e.g. CSD
+downloads, which may not be redistributed) appear locally as "Local only" and are never published.
+
+## Limitations
+
+* This is a screening tool. As the paper notes, it finds *potential* modes. Energetics, sterics and
+  guest effects need force-field or DFT follow-up.
+* The model is all-or-nothing: an angle or torsion is either fixed or completely free. A mechanism
+  or a "flexible" regime therefore means that the deformation is possible without distorting any
+  rigid body, not that it costs no energy. In the material, the released angles and torsions,
+  non-bonded interactions and guests still resist it. The reported E and F measure the geometric
+  mismatch at the joints (Ų), not an energy.
+* Bodies are geometric: atoms have no size, so very large deformations can pass through each other.
+  Inspect the deformed frames.
+* Bonds come from covalent radii (+0.45 Å). Only the first disorder component is kept, and partially
+  occupied sites are kept as full atoms.
+* Frameworks with fewer than 3 periodic dimensions (layers, chains) have no bonds, and so no
+  constraints, in the remaining directions. The model reports them as flexible there, although
+  interlayer or interchain interactions may hold them in place. A warning is shown.
+
+## License
+
+MIT, see `LICENSE`. The bundled three.js is MIT-licensed as well. The example structures come from
+the Crystallography Open Database and are in the public domain (CC0); please cite the original
+publications listed in `netsunhinged/examples/README.md`.

netsunhinged-0.1.0/netsunhinged/__init__.py

@@ -0,0 +1,18 @@
+"""NetsUnhinged - large-amplitude flexibility of framework materials (MOFs, ZIFs, zeolites)
+from rigid-body / hinge models.
+
+Implements and generalises the approach of Sarkisov, Martin, Haranczyk & Smit,
+"On the Flexibility of Metal-Organic Frameworks", J. Am. Chem. Soc. 2014, 136, 2228.
+"""
+
+from .cif import read_cif
+from .structure import Structure
+from .model import MechanicalModel, ModelOptions, preset
+
+__all__ = ["read_cif", "Structure", "MechanicalModel", "ModelOptions", "preset", "load"]
+__version__ = "0.1.0"
+
+
+def load(path):
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        return Structure(read_cif(fh.read()))

netsunhinged-0.1.0/netsunhinged/__main__.py

@@ -0,0 +1,83 @@
+"""Command line: ``python -m netsunhinged [serve|analyze] ...``"""
+
+import argparse
+import json
+import sys
+
+import numpy as np
+
+
+def cmd_analyze(args):
+    from . import deform, load, rigidity
+    from .model import MechanicalModel, ModelOptions, preset
+
+    rows = []
+    for path in args.cif:
+        st = load(path)
+        if args.options:
+            with open(args.options, encoding="utf-8") as fh:
+                opts = ModelOptions.from_dict(json.load(fh))
+        else:
+            opts = preset(st, args.preset)
+        m = MechanicalModel(st, opts)
+        rig = rigidity.analyze(m)
+        print(f"\n=== {path}  ({st.formula(st.framework)}, {st.N} atoms, {st.n_guest} guest atoms)")
+        for w in st.warnings:
+            print("  warning:", w)
+        s = m.summary()
+        print(f"  model: {s['n_bodies']} rigid bodies, {s['n_hinges']} hinges, "
+              f"{s['n_ball_joints']} ball joints, {s['n_flex_angle_atoms']} pivot atoms")
+        print(f"  infinitesimal: {rig['n_macroscopic']} cell-changing mechanism(s), "
+              f"{rig['n_internal']} internal mechanism(s)")
+        for k, md in enumerate(rig["macroscopic_modes"]):
+            print(f"    mode {k + 1}: {md['kind']}: {md['description']}")
+        verdict = "-"
+        if not args.no_finite:
+            regimes = list(deform.REGIMES) + (list(deform.EXTENDED) if args.extended else [])
+            _, res, verdict, dt = deform.run_all(
+                m, regimes=regimes, step=args.step, metric=args.metric,
+                thr=args.thr, thr2=args.thr2, modes=rig["macroscopic_modes"])
+            print(f"  finite deformation ({dt:.1f} s):")
+            key = "F" if args.metric == "relative" else "E"
+            for name, r in res.items():
+                mx = max(p[key] for p in r["points"])
+                print(f"    {name:8s} {r['classification']:14s} max {key} = {mx:9.2e}  {r['detail']}")
+            print(f"  VERDICT: {verdict.upper()}")
+        rows.append((path, rig["n_macroscopic"], verdict))
+    if len(rows) > 1:
+        print("\nsummary:")
+        for path, nm, v in rows:
+            print(f"  {v:14s} {nm} mode(s)  {path}")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="netsunhinged", description=__doc__)
+    sub = p.add_subparsers(dest="cmd")
+    s = sub.add_parser("serve", help="start the interactive web app")
+    s.add_argument("--port", type=int, default=8765)
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--no-browser", action="store_true")
+    a = sub.add_parser("analyze", help="analyse CIF files from the command line")
+    a.add_argument("cif", nargs="+")
+    a.add_argument("--preset", default="auto",
+                   choices=["auto", "paper", "zeolite", "rigid", "bondbend", "donor_pivots"])
+    a.add_argument("--options", help="JSON file with model options (as exported by the app)")
+    a.add_argument("--step", type=float, default=0.02)
+    a.add_argument("--metric", default="relative", choices=["relative", "absolute"])
+    a.add_argument("--thr", type=float, default=0.01)
+    a.add_argument("--thr2", type=float, default=0.05)
+    a.add_argument("--extended", action="store_true", help="also run fully relaxed regimes")
+    a.add_argument("--no-finite", action="store_true", help="only infinitesimal analysis")
+    args = p.parse_args(argv)
+    if args.cmd == "analyze":
+        cmd_analyze(args)
+    else:
+        from .server import serve
+        if args.cmd is None:
+            serve()
+        else:
+            serve(args.host, args.port, not args.no_browser)
+
+
+if __name__ == "__main__":
+    sys.exit(main())