structure-clustering 1.1.0__tar.gz

structure_clustering-1.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,99 @@
+name: Wheels
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_sdist:
+    name: Build SDist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - name: Check metadata
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: yezz123/setup-uv@v4
+
+      - uses: pypa/cibuildwheel@v2.20
+        env:
+          CIBW_BUILD: "cp37-* cp38-* cp39-* cp310-* cp311-* cp312-*" # https://cibuildwheel.readthedocs.io/en/stable/options/#build-skip
+          CIBW_SKIP: "*-win32 *-musllinux_x86_64 *_i686" # Skip 32 bit architectures, musllinux, and i686
+          CIBW_BEFORE_ALL_LINUX: >
+            yum install -y wget &&
+            cd / &&  mkdir boost && cd boost &&
+            wget --no-check-certificate 'https://sourceforge.net/projects/boost/files/boost/1.86.0/boost_1_86_0.tar.bz2' && 
+            tar xf boost_1_86_0.tar.bz2 &&
+            mv boost_1_86_0 boost
+          CIBW_BEFORE_ALL_WINDOWS: >
+            cd / &&  mkdir boost && cd boost &&
+            curl -L -o boost_1_86_0.zip https://sourceforge.net/projects/boost/files/boost/1.86.0/boost_1_86_0.zip/download && 
+            tar xf boost_1_86_0.zip &&
+            ren boost_1_86_0 boost
+
+      - name: Verify clean directory
+        run: git diff --exit-code
+        shell: bash
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  upload_all:
+    name: Upload if release
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          merge-multiple: true
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+          print-hash: true

structure_clustering-1.1.0/.gitignore

@@ -0,0 +1,144 @@
+# Using https://github.com/github/gitignore/blob/master/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/_generate/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+_skbuild/
+.pyodide-xbuildenv/

structure_clustering-1.1.0/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.15...3.29)
+
+project(_core LANGUAGES CXX)
+
+set(PYBIND11_FINDPYTHON ON)
+find_package(pybind11 CONFIG REQUIRED)
+
+include_directories("/boost/boost")
+
+file(GLOB CPP_FILES src/*.cpp)
+pybind11_add_module(_core ${CPP_FILES})
+
+install(TARGETS _core DESTINATION structure_clustering)

structure_clustering-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Michael Gatt.
+
+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.

structure_clustering-1.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.1
+Name: structure_clustering
+Version: 1.1.0
+Summary:  Python package to cluster molecular structures into groups of similar ones.
+Author: Gabriel Schöpfer, Milan Ončák
+Author-Email: Michael Gatt <Michael.Gatt@student.uibk.ac.at>
+Maintainer-Email: Michael Gatt <Michael.Gatt@student.uibk.ac.at>
+License: MIT License
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Documentation, https://github.com/photophys/structure_clustering/blob/master/README.md
+Project-URL: Repository, https://github.com/photophys/structure_clustering
+Project-URL: Issues, https://github.com/photophys/structure_clustering/issues
+Requires-Python: >=3.7
+Requires-Dist: argparse
+Requires-Dist: toml
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# structure_clustering
+
+**structure_clustering is a Python package to cluster molecular structures into groups of similar ones.** It provides a command-line interface to perform clustering of a multi-xyz file, or you can use it within your Python code.
+
+<img src="https://github.com/user-attachments/assets/fef206d6-e039-49ce-911d-627068841853" width="50%" />[^1]
+
+[^1]: The figure shows exemplary clusters from Ag⁺(H₂O)₄ structures.
+
+
+## Installation
+
+You can install structure_clustering via pip:
+```bash
+pip install structure_clustering
+```
+
+For most platforms, prebuilt wheels are available. If you need (or prefer) to compile and build the wheel yourself, ensure that the [Boost Graph Library](https://www.boost.org/doc/libs/release/libs/graph/doc/index.html) is available system-wide.
+
+
+## Using the Command-Line interface
+You can invoke the structure_clustering script using the `structure_clustering` command.
+
+```bash
+usage: structure_clustering <xyz_file> [--config CONFIG] [--output OUTPUT] [--disconnected]
+
+Cluster molecular structures into groups.
+
+positional arguments:
+  xyz_file         path of the multi-xyz-file containing the structures
+
+options:
+  --config CONFIG  path of the config TOML file
+  --output OUTPUT  path of the resulting output file, defaults to <xyz_file>.sc.dat
+  --disconnected   if you want to include disconnected graphs
+  -h, --help       show this help message and exit
+```
+
+For example, to cluster your xyz file:
+```bash
+structure_clustering my_structures.xyz
+```
+To specify a "special" distance for recognising O-H connectivity (see the next section), use:
+```bash
+structure_clustering my_structures.xyz --config sc_config.toml
+```
+
+In both cases, a file named `my_structures.xyz.sc.dat` will be created, which you can import at <a href="https://photophys.github.io/cluster-vis/"><img src="https://raw.githubusercontent.com/photophys/MOLGA.jl/refs/heads/main/docs/src/assets/logo.svg" height="15px" /> https://photophys.github.io/cluster-vis/</a> to visualise the results of your clustering process.
+
+The terminal output will look like this:
+```
+Loading configuration from demo_config.toml
+Using covalent radius of 1.59 for Ag
+Using pair distance of 2.3 for O-H
+Clustering does not include disconnected graphs
+
+Using 437 structures from structures.xyz
+Clustering finished <structure_clustering._core.Result object at 0x7f7c949c37b0>
+  14 clusters (total 318 structures)
+  13 unique single structures
+  132 (30.21%) structures sorted out (305 remaining)
+  cluster size: Avg=22.7 Med=4.5 Q1=2.2 Q3=23.5
+  connections/structure: Avg=12.2 Med=12.0 Q1=12.0 Q3=12.0 (all 437)
+  connections/structure: Avg=12.4 Med=12.0 Q1=12.0 Q3=12.0 (remaining 305)
+Writing output file to structures.xyz.sc.dat ...
+
+🚀 Open https://photophys.github.io/cluster-vis/ to visualize your results
+```
+
+
+## Config File
+You can use a TOML file to configure the behaviour of the command-line interface.
+```toml
+[covalent]
+He = 0.9
+Ag = 1.59
+
+[pair]
+O-H = 2.3
+
+[options]
+only_connected_graphs = true
+```
+All settings are optional. Distances are given in Angstrom. Elements are case-sensitive. If you specify `only_connected_graphs` in the config file, this will overwrite your setting from the command-line switch.
+
+
+## Demo Code
+```py
+import structure_clustering
+from structure_clustering import Structure, Atom
+
+sc_machine = structure_clustering.Machine()
+
+sc_machine.setCovalentRadius(1, 0.42)  # change hydrogen covalent radius to 0.42
+sc_machine.addPairDistance(8, 1, 2.3)  # extend max distance for O-H pairs to 2.3 Ang
+
+sc_machine.setOnlyConnectedGraphs(True)  # only include fully connected graphs (default)
+
+# you will need some structures
+population = structure_clustering.import_multi_xyz("structs.xyz")
+
+# you can also create your structures programmatically
+structure = Structure()
+structure.addAtom(Atom(8, -1.674872668, 0.0, -0.984966492))
+structure.addAtom(Atom(1, -1.674872668, 0.759337, -0.388923492))
+structure.addAtom(Atom(1, -1.674872668, -0.759337, -0.388923492))
+population += [structure]  # add this structure to our population
+
+sc_result = sc_machine.cluster(population)
+
+print("clusters", sc_result.clusters)
+print("singles", sc_result.singles)
+
+# Output (indices from the original structure list):
+# clusters [[0, 11], [1, 2, 4, 6, 12, 13, 14, 15, 19], [3, 17, 18, 23]]
+# singles [9, 16, 22]
+```
+
+
+## License
+structure_clustering is licensed under the MIT License. See the [LICENSE file](LICENSE) for more details.

structure_clustering-1.1.0/README.md

@@ -0,0 +1,120 @@
+# structure_clustering
+
+**structure_clustering is a Python package to cluster molecular structures into groups of similar ones.** It provides a command-line interface to perform clustering of a multi-xyz file, or you can use it within your Python code.
+
+<img src="https://github.com/user-attachments/assets/fef206d6-e039-49ce-911d-627068841853" width="50%" />[^1]
+
+[^1]: The figure shows exemplary clusters from Ag⁺(H₂O)₄ structures.
+
+
+## Installation
+
+You can install structure_clustering via pip:
+```bash
+pip install structure_clustering
+```
+
+For most platforms, prebuilt wheels are available. If you need (or prefer) to compile and build the wheel yourself, ensure that the [Boost Graph Library](https://www.boost.org/doc/libs/release/libs/graph/doc/index.html) is available system-wide.
+
+
+## Using the Command-Line interface
+You can invoke the structure_clustering script using the `structure_clustering` command.
+
+```bash
+usage: structure_clustering <xyz_file> [--config CONFIG] [--output OUTPUT] [--disconnected]
+
+Cluster molecular structures into groups.
+
+positional arguments:
+  xyz_file         path of the multi-xyz-file containing the structures
+
+options:
+  --config CONFIG  path of the config TOML file
+  --output OUTPUT  path of the resulting output file, defaults to <xyz_file>.sc.dat
+  --disconnected   if you want to include disconnected graphs
+  -h, --help       show this help message and exit
+```
+
+For example, to cluster your xyz file:
+```bash
+structure_clustering my_structures.xyz
+```
+To specify a "special" distance for recognising O-H connectivity (see the next section), use:
+```bash
+structure_clustering my_structures.xyz --config sc_config.toml
+```
+
+In both cases, a file named `my_structures.xyz.sc.dat` will be created, which you can import at <a href="https://photophys.github.io/cluster-vis/"><img src="https://raw.githubusercontent.com/photophys/MOLGA.jl/refs/heads/main/docs/src/assets/logo.svg" height="15px" /> https://photophys.github.io/cluster-vis/</a> to visualise the results of your clustering process.
+
+The terminal output will look like this:
+```
+Loading configuration from demo_config.toml
+Using covalent radius of 1.59 for Ag
+Using pair distance of 2.3 for O-H
+Clustering does not include disconnected graphs
+
+Using 437 structures from structures.xyz
+Clustering finished <structure_clustering._core.Result object at 0x7f7c949c37b0>
+  14 clusters (total 318 structures)
+  13 unique single structures
+  132 (30.21%) structures sorted out (305 remaining)
+  cluster size: Avg=22.7 Med=4.5 Q1=2.2 Q3=23.5
+  connections/structure: Avg=12.2 Med=12.0 Q1=12.0 Q3=12.0 (all 437)
+  connections/structure: Avg=12.4 Med=12.0 Q1=12.0 Q3=12.0 (remaining 305)
+Writing output file to structures.xyz.sc.dat ...
+
+🚀 Open https://photophys.github.io/cluster-vis/ to visualize your results
+```
+
+
+## Config File
+You can use a TOML file to configure the behaviour of the command-line interface.
+```toml
+[covalent]
+He = 0.9
+Ag = 1.59
+
+[pair]
+O-H = 2.3
+
+[options]
+only_connected_graphs = true
+```
+All settings are optional. Distances are given in Angstrom. Elements are case-sensitive. If you specify `only_connected_graphs` in the config file, this will overwrite your setting from the command-line switch.
+
+
+## Demo Code
+```py
+import structure_clustering
+from structure_clustering import Structure, Atom
+
+sc_machine = structure_clustering.Machine()
+
+sc_machine.setCovalentRadius(1, 0.42)  # change hydrogen covalent radius to 0.42
+sc_machine.addPairDistance(8, 1, 2.3)  # extend max distance for O-H pairs to 2.3 Ang
+
+sc_machine.setOnlyConnectedGraphs(True)  # only include fully connected graphs (default)
+
+# you will need some structures
+population = structure_clustering.import_multi_xyz("structs.xyz")
+
+# you can also create your structures programmatically
+structure = Structure()
+structure.addAtom(Atom(8, -1.674872668, 0.0, -0.984966492))
+structure.addAtom(Atom(1, -1.674872668, 0.759337, -0.388923492))
+structure.addAtom(Atom(1, -1.674872668, -0.759337, -0.388923492))
+population += [structure]  # add this structure to our population
+
+sc_result = sc_machine.cluster(population)
+
+print("clusters", sc_result.clusters)
+print("singles", sc_result.singles)
+
+# Output (indices from the original structure list):
+# clusters [[0, 11], [1, 2, 4, 6, 12, 13, 14, 15, 19], [3, 17, 18, 23]]
+# singles [9, 16, 22]
+```
+
+
+## License
+structure_clustering is licensed under the MIT License. See the [LICENSE file](LICENSE) for more details.

structure_clustering-1.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["scikit-build-core", "pybind11"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "structure_clustering"
+version = "1.1.0"
+description = " Python package to cluster molecular structures into groups of similar ones."
+readme = "README.md"
+authors = [
+  { name = "Michael Gatt", email = "Michael.Gatt@student.uibk.ac.at" },
+  { name = "Gabriel Schöpfer" },
+  { name = "Milan Ončák" },
+]
+maintainers = [
+  { name = "Michael Gatt", email = "Michael.Gatt@student.uibk.ac.at" },
+]
+requires-python = ">=3.7"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = ["argparse", "toml", "numpy"]
+license = { text = "MIT License" }
+
+[project.urls]
+Documentation = "https://github.com/photophys/structure_clustering/blob/master/README.md"
+Repository = "https://github.com/photophys/structure_clustering"
+Issues = "https://github.com/photophys/structure_clustering/issues"
+
+[project.scripts]
+structure_clustering = "structure_clustering.__main__:main"

structure_clustering-1.1.0/src/Atom.hpp

@@ -0,0 +1,30 @@
+#ifndef __ATOM__
+#define __ATOM__
+
+#include <iostream>
+
+class Position {
+    double _x, _y, _z;
+
+public:
+    Position(const double x, const double y, const double z) : _x(x), _y(y), _z(z) {}
+    double x() const { return _x; }
+    double y() const { return _y; }
+    double z() const { return _z; }
+};
+
+class Atom {
+    int _atomicNumber;
+    Position _position;
+
+public:
+    Atom(const int &atomType, const Position &position)
+        : _atomicNumber(atomType), _position(position) {}
+    Atom(const int &atomType, const double x, const double y, const double z)
+        : _atomicNumber(atomType), _position(Position(x, y, z)) {}
+
+    int atomicNumber() const { return _atomicNumber; }
+    Position position() const { return _position; }
+};
+
+#endif