synthetmic 0.1.0__tar.gz

synthetmic-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+assets/
+plots/

synthetmic-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.3

synthetmic-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025 synthetic-miscrostructures
+
+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.

synthetmic-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: synthetmic
+Version: 0.1.0
+Summary: A Python package for generating synthetic Laguerre polycrystalline microstructures
+Project-URL: homepage, https://github.com/lpm-dev/lpm
+Project-URL: issues, https://github.com/lpm-dev/lpm/issues
+Author-email: "R. O. Ibraheem" <ibraheem.abdulrasheed@gmail.com>, "D. P. Bourne" <D.Bourne@hw.ac.uk>, "S. M. Roper" <Steven.Roper@glasgow.ac.uk>
+Maintainer-email: "R. O. Ibraheem" <ibraheem.abdulrasheed@gmail.com>, "D. P. Bourne" <D.Bourne@hw.ac.uk>, "S. M. Roper" <Steven.Roper@glasgow.ac.uk>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12.3
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: numpy>=2.3.0
+Requires-Dist: pysdot>=0.2.36
+Requires-Dist: pyvista[jupyter]>=0.45.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: vtk>=9.4.2
+Provides-Extra: cli
+Requires-Dist: click>=8.2.1; extra == 'cli'
+Provides-Extra: examples
+Provides-Extra: tests
+Requires-Dist: pytest>=8.4.1; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# SynthetMic
+A Python package for generating synthetic polycrystalline microstructures using Laguerre diagrams, powered by [pysdot](https://github.com/sd-ot/pysdot).
+
+## Installation
+To install the latest version of the package via `pip`, run
+```
+pip install synthetmic
+```
+> If you are using `uv` to manage your project, run the following command instead:
+>
+> uv add synthetmic
+
+## Usage
+To use this package to generate synthetic microstructures, you need to import the generator class as follows:
+```python
+from synthetmic import LaguerreDiagramGenerator
+```
+
+Create an instance of the class with the default arguments:
+```python
+generator = LaguerreDiagramGenerator()
+```
+or with custom parameters:
+```python
+generator = LaguerreDiagramGenerator(
+                tol=0.1,
+                n_iter=5,
+                damp_param=1.0,
+                verbose=True,
+)
+```
+
+We can fit this class to some data by calling the `fit` method. For example, we can create a Laguerre tessellation of the unit cube [0, 1] x [0, 1] x [0, 1] with 1000 cells of equal volume as follows:
+```python
+import numpy as np
+    
+domain = np.array([[0, 1],[0, 1],[0, 1]])
+domain_vol = np.prod(domain[:, 1] - domain[:, 0])
+    
+n_grains = 1000
+    
+seeds = np.column_stack(
+        [np.random.uniform(low=d[0], high=d[1], size=n_grains) for d in domain]
+)
+volumes = (np.ones(n_grains) / n_grains) * domain_vol
+    
+# call the fit method on data
+generator.fit(
+        seeds=seeds,
+        volumes=volumes,
+        domain=domain,
+)
+```
+
+After calling the fit method, you can use the instance to get various properties of the diagram, e.g., get the centroids and vertices of the cells:
+```python
+centroids = generator.get_centroids()
+vertices = generator.get_vertices()
+    
+print("diagram centroids:\n", centroids)
+print("diagram vertices:\n", vertices)
+```
+
+You can plot the diagram in static or interactive mode by using the fitted instance:
+```python
+from synthetmic.plot import plot_cells_as_pyvista_fig
+plot_cells_as_pyvista_fig(
+        generator=generator,
+        interactive=True,
+        save_path="./example_diagram.html",
+)
+```
+
+The generated HTML file can be viewed via any browser of your choice.
+
+If you prefer a static figure, turn off `interactive` and save figure as pdf (can also be saved as eps, ps, tex, and svg):
+```python
+plot_cells_as_pyvista_fig(
+        generator=generator,
+        interactive=False,
+        save_path="./example_diagram.pdf",
+    )
+```
+
+To see more usage examples, see the `examples` folder or check below on how to run them via `cli.py`.
+
+
+## Working with source codes
+### Build from source
+If you would like to build this project from source either for development purposes or for any other reason, it is recommended to install [uv](https://docs.astral.sh/uv/). This is what is adopted in this project. To install uv, follow the instructions in this [link](https://docs.astral.sh/uv/getting-started/installation/).
+
+If you don't want to use uv, you can use other alternatives like [pip](https://pip.pypa.io/en/stable/).
+
+The following instructions use uv for building synthetmic from source.
+
+1. Clone the repository by running
+
+    ```
+    git clone https://github.com/synthetic-microstructures/synthetmic
+    ```
+
+1. Create a python virtual environment by running
+
+    ```
+     uv venv .venv --python PYTHON_VERSION
+    ```
+    > Here, PYTHON_VERSION is the supported Python version. Note that this project requires version >=3.12.3
+
+1. Activate the virtual environment by running
+
+    ```
+    source .venv/bin/activate
+    ```
+
+1. Prepare all modules and dependencies by running the following:
+
+    ```
+    uv sync --all-extras
+    ```
+
+### Running examples
+We created a command line interface (cli) for recreating some of the examples provided in the this [paper](https://www.tandfonline.com/doi/full/10.1080/14786435.2020.1790053) (and lots more!).
+
+To check the available commands in the cli, run
+
+```
+python cli.py --help
+```
+
+There are currently two commands available in the cli: `recreate` and `analyse`.
+
+You can check information about each of these commands by running
+
+```
+python cli.py COMMAND --help
+```
+where `COMMAND` is any of the commands.
+
+Running a command with its appropriate args is simple. For instance, if you would like to recreate some of the two-dimensional examples in the above-mentioned paper, and save the generated plots in the ./plots dir, run
+
+```
+python cli.py recreate --example 2d --save-dir ./plots
+```
+You can do the same for three-dimension examples. You can pass the flag `--interactive` or `-i` to save the generated plots as a `.html` file, which can then be opened in a browser to interact with them:
+
+```
+python cli.py recreate --example 2d --save-dir ./plots --interactive
+```
+
+> Note: by default, the generated plots will be saved as `.pdf`. Passing `--interactive` flag to 2d case will be skipped since this is not that interesting for interactivity.
+
+### Running tests
+To run all tests, run
+
+```
+pytest -v tests
+```
+
+## References
+If you use this package in your research, please refer to the link to this project. Additionally, please consider citing the following paper:
+```bibtex
+@article{Bourne01112020,
+author = {D. P. Bourne and P. J. J. Kok and S. M. Roper and W. D. T. Spanjer},
+title = {Laguerre tessellations and polycrystalline microstructures: a fast algorithm for generating grains of given volumes},
+journal = {Philosophical Magazine},
+volume = {100},
+number = {21},
+pages = {2677--2707},
+year = {2020},
+publisher = {Taylor \& Francis},
+doi = {10.1080/14786435.2020.1790053},
+URL = {https://doi.org/10.1080/14786435.2020.1790053},
+eprint = {https://doi.org/10.1080/14786435.2020.1790053}
+}
+```
+You may also be interested in some of our other libraries:
+* [LPM](https://github.com/DPBourne/Laguerre-Polycrystalline-Microstructures) - MATLAB code for generating synthetic polycrystalline microstructures using Laguerre diagrams
+* [pyAPD](https://github.com/mbuze/PyAPD) - a Python library for computing *anisotropic* Laguerre diagrams

synthetmic-0.1.0/README.md

@@ -0,0 +1,178 @@
+# SynthetMic
+A Python package for generating synthetic polycrystalline microstructures using Laguerre diagrams, powered by [pysdot](https://github.com/sd-ot/pysdot).
+
+## Installation
+To install the latest version of the package via `pip`, run
+```
+pip install synthetmic
+```
+> If you are using `uv` to manage your project, run the following command instead:
+>
+> uv add synthetmic
+
+## Usage
+To use this package to generate synthetic microstructures, you need to import the generator class as follows:
+```python
+from synthetmic import LaguerreDiagramGenerator
+```
+
+Create an instance of the class with the default arguments:
+```python
+generator = LaguerreDiagramGenerator()
+```
+or with custom parameters:
+```python
+generator = LaguerreDiagramGenerator(
+                tol=0.1,
+                n_iter=5,
+                damp_param=1.0,
+                verbose=True,
+)
+```
+
+We can fit this class to some data by calling the `fit` method. For example, we can create a Laguerre tessellation of the unit cube [0, 1] x [0, 1] x [0, 1] with 1000 cells of equal volume as follows:
+```python
+import numpy as np
+    
+domain = np.array([[0, 1],[0, 1],[0, 1]])
+domain_vol = np.prod(domain[:, 1] - domain[:, 0])
+    
+n_grains = 1000
+    
+seeds = np.column_stack(
+        [np.random.uniform(low=d[0], high=d[1], size=n_grains) for d in domain]
+)
+volumes = (np.ones(n_grains) / n_grains) * domain_vol
+    
+# call the fit method on data
+generator.fit(
+        seeds=seeds,
+        volumes=volumes,
+        domain=domain,
+)
+```
+
+After calling the fit method, you can use the instance to get various properties of the diagram, e.g., get the centroids and vertices of the cells:
+```python
+centroids = generator.get_centroids()
+vertices = generator.get_vertices()
+    
+print("diagram centroids:\n", centroids)
+print("diagram vertices:\n", vertices)
+```
+
+You can plot the diagram in static or interactive mode by using the fitted instance:
+```python
+from synthetmic.plot import plot_cells_as_pyvista_fig
+plot_cells_as_pyvista_fig(
+        generator=generator,
+        interactive=True,
+        save_path="./example_diagram.html",
+)
+```
+
+The generated HTML file can be viewed via any browser of your choice.
+
+If you prefer a static figure, turn off `interactive` and save figure as pdf (can also be saved as eps, ps, tex, and svg):
+```python
+plot_cells_as_pyvista_fig(
+        generator=generator,
+        interactive=False,
+        save_path="./example_diagram.pdf",
+    )
+```
+
+To see more usage examples, see the `examples` folder or check below on how to run them via `cli.py`.
+
+
+## Working with source codes
+### Build from source
+If you would like to build this project from source either for development purposes or for any other reason, it is recommended to install [uv](https://docs.astral.sh/uv/). This is what is adopted in this project. To install uv, follow the instructions in this [link](https://docs.astral.sh/uv/getting-started/installation/).
+
+If you don't want to use uv, you can use other alternatives like [pip](https://pip.pypa.io/en/stable/).
+
+The following instructions use uv for building synthetmic from source.
+
+1. Clone the repository by running
+
+    ```
+    git clone https://github.com/synthetic-microstructures/synthetmic
+    ```
+
+1. Create a python virtual environment by running
+
+    ```
+     uv venv .venv --python PYTHON_VERSION
+    ```
+    > Here, PYTHON_VERSION is the supported Python version. Note that this project requires version >=3.12.3
+
+1. Activate the virtual environment by running
+
+    ```
+    source .venv/bin/activate
+    ```
+
+1. Prepare all modules and dependencies by running the following:
+
+    ```
+    uv sync --all-extras
+    ```
+
+### Running examples
+We created a command line interface (cli) for recreating some of the examples provided in the this [paper](https://www.tandfonline.com/doi/full/10.1080/14786435.2020.1790053) (and lots more!).
+
+To check the available commands in the cli, run
+
+```
+python cli.py --help
+```
+
+There are currently two commands available in the cli: `recreate` and `analyse`.
+
+You can check information about each of these commands by running
+
+```
+python cli.py COMMAND --help
+```
+where `COMMAND` is any of the commands.
+
+Running a command with its appropriate args is simple. For instance, if you would like to recreate some of the two-dimensional examples in the above-mentioned paper, and save the generated plots in the ./plots dir, run
+
+```
+python cli.py recreate --example 2d --save-dir ./plots
+```
+You can do the same for three-dimension examples. You can pass the flag `--interactive` or `-i` to save the generated plots as a `.html` file, which can then be opened in a browser to interact with them:
+
+```
+python cli.py recreate --example 2d --save-dir ./plots --interactive
+```
+
+> Note: by default, the generated plots will be saved as `.pdf`. Passing `--interactive` flag to 2d case will be skipped since this is not that interesting for interactivity.
+
+### Running tests
+To run all tests, run
+
+```
+pytest -v tests
+```
+
+## References
+If you use this package in your research, please refer to the link to this project. Additionally, please consider citing the following paper:
+```bibtex
+@article{Bourne01112020,
+author = {D. P. Bourne and P. J. J. Kok and S. M. Roper and W. D. T. Spanjer},
+title = {Laguerre tessellations and polycrystalline microstructures: a fast algorithm for generating grains of given volumes},
+journal = {Philosophical Magazine},
+volume = {100},
+number = {21},
+pages = {2677--2707},
+year = {2020},
+publisher = {Taylor \& Francis},
+doi = {10.1080/14786435.2020.1790053},
+URL = {https://doi.org/10.1080/14786435.2020.1790053},
+eprint = {https://doi.org/10.1080/14786435.2020.1790053}
+}
+```
+You may also be interested in some of our other libraries:
+* [LPM](https://github.com/DPBourne/Laguerre-Polycrystalline-Microstructures) - MATLAB code for generating synthetic polycrystalline microstructures using Laguerre diagrams
+* [pyAPD](https://github.com/mbuze/PyAPD) - a Python library for computing *anisotropic* Laguerre diagrams

synthetmic-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "synthetmic"
+version = "0.1.0"
+description = "A Python package for generating synthetic Laguerre polycrystalline microstructures"
+readme = "README.md"
+authors = [
+    { name = "R. O. Ibraheem", email = "ibraheem.abdulrasheed@gmail.com" },
+    { name = "D. P. Bourne", email = "D.Bourne@hw.ac.uk" },
+    { name = "S. M. Roper", email = "Steven.Roper@glasgow.ac.uk" },
+]
+maintainers = [
+    { name = "R. O. Ibraheem", email = "ibraheem.abdulrasheed@gmail.com" },
+    { name = "D. P. Bourne", email = "D.Bourne@hw.ac.uk" },
+    { name = "S. M. Roper", email = "Steven.Roper@glasgow.ac.uk" }
+]
+requires-python = ">=3.12.3"
+dependencies = [
+    "matplotlib>=3.10.3",
+    "numpy>=2.3.0",
+    "pysdot>=0.2.36",
+    "pyvista[jupyter]>=0.45.2",
+    "scipy>=1.15.3",
+    "vtk>=9.4.2",
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+homepage = "https://github.com/lpm-dev/lpm"
+issues = "https://github.com/lpm-dev/lpm/issues"
+
+[project.optional-dependencies]
+cli = [
+    "click>=8.2.1",
+]
+examples = []
+tests = [
+    "pytest>=8.4.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.github",
+  "/tests",
+  "examples",
+  "assets",
+  "cli.py",
+]

synthetmic-0.1.0/src/synthetmic/__init__.py

@@ -0,0 +1,5 @@
+from .generate import LaguerreDiagramGenerator
+
+__all__ = [
+    "LaguerreDiagramGenerator",
+]