granular 0.0.0__tar.gz

granular-0.0.0/LICENSE

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

granular-0.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.1
+Name: granular
+Version: 0.0.0
+Summary: python library for the numerical simulation of granular materials
+Home-page: https://pypi.org/project/granular/
+Author: Steffen Richters-Finger
+Author-email: srichters@uni-muenster.de
+License: MIT
+Project-URL: Source, https://github.com/RichtersFinger/granular
+Platform: UNKNOWN
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# granular
+library for the numerical simulation of granular materials
+
+

granular-0.0.0/README.md

@@ -0,0 +1,2 @@
+# granular
+library for the numerical simulation of granular materials

granular-0.0.0/granular/geometry.py

@@ -0,0 +1,202 @@
+"""
+# geometry.py
+
+This module contains definitions that can be used to generate and process
+grain shapes that are supported by `granular`, i.e., star domains.
+
+
+## Sampling
+A sampling-process (useful for generating different representations of
+grains) can be performed using the `SamplingStrategy`-classes. These,
+again, require a `SamplingContext` storing information like number of
+samples.
+
+Generate an array of equidistantly distributed samples for the
+function x**2 by entering
+```
+>>> from granular.geometry import EquidistantSampling, SamplingContext
+>>> samples = EquidistantSampling.sample(shape=lambda x: x**2, context=SamplingContext())
+>>> np.shape(samples)
+(50, 2)
+```
+
+## Shape generating functions
+This module provides functions that can be used to generate `Shape`s,
+i.e., functions which themselves represent closed, planar curves. For
+example, using the factory `shape_superformula`, a star-like `Shape` can
+be created by
+```
+>>> from granular.geometry import shape_superformula
+>>> shape = shape_superformula((2, 9, 9), 5, 1.0)
+>>> shape([1, 2, 3])
+array([0.37628812, 0.77859841, 0.7103601])
+```
+"""
+
+from typing import TypeAlias, Callable, Optional
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from math import cos, sin
+import numpy as np
+from numpy.typing import NDArray
+from scipy import optimize
+
+Shape: TypeAlias = Callable[[float | NDArray], float | NDArray]
+
+
+@dataclass
+class SamplingContext:
+    """
+    Record class representing information on a sampling context.
+
+    Keyword arguments:
+    domain -- domain over which the sampling should be done
+              (default corresponds to an interval [0:1])
+    num -- total number of samples
+           (default 50)
+    endpoint -- if `True`, the first and last sample are identical
+                (default `False`)
+    """
+
+    domain: list = field(default_factory=lambda: [0.0, 1.0])
+    num: int = 50
+    endpoint: bool = False
+
+
+class SamplingStrategy(ABC):
+    """
+    Interface for sampling strategies.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def samples(
+        shape: Shape,
+        context: Optional[SamplingContext] = None
+    ) -> NDArray:
+        """
+        Returns an array of `num` sample locations based on `shape`.
+
+        Keyword arguments:
+        shape -- callable function generating a shape to be sampled
+        context -- sampling context
+                   (default uses a `SamplingContext` with default
+                   values)
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def sample(
+        cls,
+        shape: Shape,
+        context: Optional[SamplingContext] = None,
+        values_only: bool = False
+    ) -> NDArray:
+        """
+        Returns an array of `num` sampled locations based on `shape`
+        as pairs of sample position and sampled value (shape=(num, 2)).
+
+        Keyword arguments:
+        shape -- callable function generating a shape to be sampled
+        context -- sampling context
+                   (default uses a `SamplingContext` with default
+                   values)
+        values_only -- if `True`, the returned array only contains the
+                       sampled values (shape=(num,))
+        """
+
+        x = cls.samples(shape, context=context)
+        y = shape(x)
+
+        if values_only:
+            return y
+        return np.stack((x, y), axis=-1)
+
+
+class EquidistantSampling(SamplingStrategy):
+    """
+    Samples for equidistant sampling.
+    """
+
+    @staticmethod
+    def samples(
+        shape: Shape,
+        context: Optional[SamplingContext] = None
+    ) -> NDArray:
+        return np.linspace(
+            *(context.domain or [0.0, 1.0]),
+            num=context.num,
+            endpoint=context.endpoint
+        )
+
+
+class FavorCurvatureSampling(SamplingStrategy):
+    """
+    Samples with higher frequency in regions of greater curvature.
+    """
+
+    @staticmethod
+    def samples(
+        shape: Shape,
+        context: Optional[SamplingContext] = None
+    ) -> NDArray:
+
+        raise NotImplementedError
+
+
+def shape_superformula(
+    n: tuple[int, int, int],
+    m: int, r: float,
+    vectorize: bool = True
+) -> Shape:
+    """
+    Returns a callable function that generates a planar and closed
+    curve based on the superformula.
+
+    r(p) ~ r * [|cos(mp/4)|**n2 + |sin(mp/4)|**n3]**(-1/n1)
+
+    Keyword arguments:
+    n -- three-tuple containing the interger values `n1`, `n2`, `n3`
+    m -- angular frequency `m`
+    r -- radius of the bounding sphere
+    vectorize -- if `True`, use `np.vectorize` to make compatible with
+                 `NDArray`
+                 (default `True`)
+    """
+
+    def _generate_super(_r):
+        def __r(p):
+            return _r * (
+                (abs(cos((_p := 0.25*m*p))))**n[1]
+                + (abs(sin(_p)))**n[2]
+            )**(-1.0/n[0])
+        if vectorize:
+            return np.vectorize(__r)
+        return __r
+
+    # rescale to precisely fit bounding volume into requested size r
+    return _generate_super(
+        r/_generate_super(r)(
+            optimize.fminbound(_generate_super(-r), 0.0, 2.0*np.pi)
+        )
+    )
+
+
+def shape_fourier(
+    d: tuple[float, ...],
+    r: float,
+    vectorize: bool = True
+) -> Shape:
+    """
+    Returns a callable function that generates an irregular, planar and
+    closed curve based on the a Fourier expansion.
+
+    Keyword arguments:
+    d -- tuple of Fourier descriptors
+    r -- radius of the bounding sphere
+    vectorize -- if `True`, use `np.vectorize` to make compatible with
+                 `NDArray`
+                 (default `True`)
+    """
+
+    raise NotImplementedError

granular-0.0.0/granular/grain.py

@@ -0,0 +1,161 @@
+"""
+# grain.py
+
+This module defines the `Grain`-base class as well as more specialized
+classes and supplemental helper-functions for an efficient generation of
+`Grain`s.
+
+## Grain
+A `Grain` stores information on shape (including preprocessed
+information that is being used in the simulation afterwards). It also
+gets assigned a unique identifier via the uuid-module (uuid4).
+Furthermore, `Grain`-type classes provide a `sample`-method that can be
+issued to generate a sampled representation in the form of a `numpy`-
+`NDArray`.
+
+"""
+
+from typing import Optional
+from dataclasses import dataclass
+import uuid
+import numpy as np
+from numpy.typing import NDArray
+from scipy import optimize
+from granular.geometry \
+    import Shape, SamplingStrategy, EquidistantSampling, SamplingContext
+
+
+@dataclass
+class Representations:
+    """
+    Record class defining the storage-format of different
+    representations of `Grain`s.
+
+    Keyword arguments:
+    ground_truth -- ground truth for the shape of a `Grain`
+    sampled -- list of `NDArray`s for the sampled `Shape` at different
+               levels of detail; `sampled[0]` represents the lowest lod
+               (default `None`)
+    bounding_box -- (UNUSED) bounding box representation
+                    (default `None`)
+    bounding_sphere -- `float` characterizing size of the bounding
+                       sphere with a point of reference located at the
+                       reference point for the shape-generating function
+                       (default `None`)
+    """
+
+    ground_truth: Shape
+    sampled: Optional[list[NDArray]] = None
+    bounding_box: Optional = None
+    bounding_sphere: Optional[float] = None
+
+
+class Grain:
+    """
+    `Grain`s represent the granular units of a simulation.
+
+    Keyword arguments:
+    shape -- grain shape
+    """
+
+    def __init__(self, shape: Shape) -> None:
+        self._identifier = uuid.uuid4()
+        self._default_sampling_strategy = EquidistantSampling
+        self._default_sampling_context = SamplingContext(
+            domain=[0, np.pi],
+            num=50,
+            endpoint=False
+        )
+
+        # preprocess/analyze shape
+        self._representations = Representations(
+            ground_truth=shape,
+            sampled=[
+                self._default_sampling_strategy.sample(
+                    shape,
+                    self._default_sampling_context
+                )
+            ],
+            bounding_sphere=shape(
+                optimize.fminbound(
+                    lambda x: -shape(x), 0.0, 2.0*np.pi, xtol=1e-10
+                )
+            )
+        )
+
+    def sample(
+        self,
+        strategy: SamplingStrategy = None,
+        context: Optional[SamplingContext] = None
+    ) -> NDArray:
+        """
+        Returns an `NDArray` as returned by the provided
+        `SamplingStrategy`. The default `SamplingStrategy` corresponds
+        to `EquidistantSampling`. The default `SamplingContext` is
+        passed into the provided strategy uses a domain of `[0, np.pi]`
+        and otherwise the context's default values.
+
+        Keyword arguments:
+        strategy -- a `SamplingStrategy` used to sample the shape
+                    (default `None`)
+        context -- a `SamplingContext` passed to the provided
+                   `SamplingStrategy`
+                   (default `None`)
+        """
+
+        if strategy is None and context is None:
+            return self._representations.sampled[0]
+
+        return (strategy or self._default_sampling_strategy).sample(
+            self._representations.ground_truth,
+            context=context or self._default_sampling_context
+        )
+
+    @property
+    def identifier(self) -> str:
+        """Getter for property `identifier`."""
+        return str(self._identifier)
+
+    @property
+    def shape(self) -> Shape:
+        """Getter for property `shape`."""
+        return self._representations.ground_truth
+
+    @property
+    def lod0(self) -> NDArray:
+        """Getter for property `lod0`."""
+        return self._representations.sampled[0]
+
+    @property
+    def radius(self) -> str:
+        """Getter for property `radius` (bounding sphere)."""
+        return self._representations.bounding_sphere
+
+    @property
+    def diameter(self) -> str:
+        """Getter for property `diameter` (bounding sphere)."""
+        return 2*self._representations.bounding_sphere
+
+    def __str__(self):
+        return f"<grain {self._identifier}>"
+
+
+# TODO: derived classes for different types: spherical, super, fourier
+class SphericalGrain(Grain):
+    ...
+
+
+class SuperGrain(Grain):
+    ...
+
+
+class FourierGrain(Grain):
+    ...
+
+
+def duplicate_grain(grain: Grain) -> Grain:
+    ...
+
+
+def generate_batch(grain: Grain) -> list[Grain]:
+    ...

granular-0.0.0/granular.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.1
+Name: granular
+Version: 0.0.0
+Summary: python library for the numerical simulation of granular materials
+Home-page: https://pypi.org/project/granular/
+Author: Steffen Richters-Finger
+Author-email: srichters@uni-muenster.de
+License: MIT
+Project-URL: Source, https://github.com/RichtersFinger/granular
+Platform: UNKNOWN
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# granular
+library for the numerical simulation of granular materials
+
+

granular-0.0.0/granular.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+setup.py
+granular/__init__.py
+granular/geometry.py
+granular/grain.py
+granular.egg-info/PKG-INFO
+granular.egg-info/SOURCES.txt
+granular.egg-info/dependency_links.txt
+granular.egg-info/requires.txt
+granular.egg-info/top_level.txt

granular-0.0.0/granular.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

granular-0.0.0/granular.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy<2,>=1.26.3
+scipy<2,>=1.11.4

granular-0.0.0/granular.egg-info/top_level.txt

@@ -0,0 +1 @@
+granular

granular-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

granular-0.0.0/setup.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from setuptools import setup
+
+# read contents of README
+long_description = \
+    (Path(__file__).parent / "README.md").read_text(encoding="utf8")
+
+# read contents of requirements.txt
+requirements = \
+    (Path(__file__).parent / "requirements.txt") \
+        .read_text(encoding="utf8") \
+        .strip() \
+        .split("\n")
+
+setup(
+    version="0.0.0",
+    name="granular",
+    description="python library for the numerical simulation of granular materials",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Steffen Richters-Finger",
+    author_email="srichters@uni-muenster.de",
+    license="MIT",
+    license_files=("LICENSE",),
+    url="https://pypi.org/project/granular/",
+    project_urls={
+        "Source": "https://github.com/RichtersFinger/granular"
+    },
+    python_requires=">=3.10",
+    install_requires=requirements,
+    packages=[
+        "granular",
+    ],
+    classifiers=[
+        "Development Status :: 2 - Pre-Alpha",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering :: Physics",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Typing :: Typed",
+    ],
+)