random-fields 1.0.1__py3-none-any.whl

random_fields/__init__.py

@@ -0,0 +1 @@
+from .__version__ import __version__

random_fields/__version__.py

@@ -0,0 +1,3 @@
+__title__ = "Random Fields Generator"
+__version__ = "1.0.1"
+__author__ = "STEM team"

random_fields/generate_field.py

@@ -0,0 +1,96 @@
+from enum import Enum
+from typing import List
+import numpy as np
+import gstools as gs
+
+
+class ModelName(Enum):
+    """
+    Name of the model to be used. Options are: "Gaussian", "Exponential", "Matern", "Linear"
+    """
+    Gaussian = gs.Gaussian
+    Exponential = gs.Exponential
+    Matern = gs.Matern
+    Linear = gs.Linear
+
+
+class RandomFields:
+    """
+    Generate random fields
+    """
+
+    def __init__(self, model_name: ModelName, n_dim: int,
+                 mean: float, variance: float,
+                 v_scale_fluctuation: float, anisotropy: List[float], angle: List[float],
+                 seed: int = 14, v_dim: int = 1) -> None:
+        """
+        Initialise generation of random fields
+
+        Parameters:
+        -----------
+        model_name: str
+            Name of the model to be used. Options are: "Gaussian", "Exponential", "Matern", "Linear"
+        n_dim: int
+            The dimension of the random field
+        mean: float
+            The mean of the random field
+        variance: float
+            The variance of the random field
+        v_scale_fluctuation: float
+            The vertical scale of fluctuation of the random field
+        anisotropy: list
+            The anisotropy of the random field (per dimension)
+        angle: list
+            The angle of the random field (per dimension)
+        seed: int
+            The seed number for the random number generator
+        v_dim: int
+            The dimension of the vertical scale of fluctuation
+        """
+        # initialise model
+        if model_name.name not in ModelName.__members__:
+            raise ValueError(f'Model name: {model_name} is not supported')
+
+        if n_dim not in [1, 2, 3]:
+            raise ValueError('Only 1, 2, 3 dimensions are supported')
+
+        aux_keys = [anisotropy, angle]
+        for key in aux_keys:
+            if len(key) != n_dim - 1:
+                raise ValueError(f'Number of dimensions: {n_dim} does not match number of\
+                                 random field properties: {len(variance)}. It should be {n_dim - 1}.')
+
+        self.random_field_model = model_name.value
+        self.n_dim = n_dim
+        self.seed = seed
+        self.mean = mean
+        self.variance = variance
+        self.vertical_scale_fluctuation = v_scale_fluctuation
+        self.anisotropy = anisotropy
+        self.angle = angle
+        self.v_dim = v_dim
+        self.random_field = None
+
+    def generate(self, nodes: np.ndarray) -> None:
+        """
+        Generate random field
+
+        Parameters:
+        ------------
+        nodes: list
+            The nodes of the random field
+        """
+        # check dimensions of nodes agrees with dimensions of model
+        if nodes.shape[1] != self.n_dim:
+            raise ValueError(f'Dimensions of nodes: {nodes.shape[1]} do not match dimensions of model: {self.n_dim}')
+
+        # scale of fluctuation
+        scale_fluctuation = np.ones(self.n_dim) * self.vertical_scale_fluctuation
+
+        # apply the anisotropy to the other dimensions
+        mask = np.arange(len(scale_fluctuation)) != self.v_dim
+        scale_fluctuation[mask] = scale_fluctuation[mask] * self.anisotropy
+
+        model = self.random_field_model(dim=self.n_dim, var=self.variance, len_scale=scale_fluctuation, angles=self.angle)
+        self.random_field = gs.SRF(model, mean=self.mean, seed=self.seed)
+        self.random_field(nodes.T)

random_fields/utils.py

@@ -0,0 +1,97 @@
+import os
+import numpy as np
+import matplotlib.pylab as plt
+import matplotlib as mpl
+
+
+def plot3D(coordinates: list, random_field: list, title: str = "Random Field",
+           output_folder = "./", output_name: str = "random_field.png"):
+    """
+    Plot 3D random field
+
+    Parameters
+    ----------
+    coordinates : list
+        List of coordinates of the random field
+    random_field : list
+        List of random field values
+    title : str
+        Title of the plot
+    output_folder : str
+        Output folder
+    output_name : str
+        Output fine name
+    """
+    # create output folder
+    if not os.path.exists(output_folder):
+        os.makedirs(output_folder)
+
+    # make plot
+    fig = plt.figure(1, figsize=(6, 5))
+    ax = fig.add_subplot(projection='3d')
+    ax.set_position([0.1, 0.1, 0.8, 0.8])
+    # rotate the axes so that y is vertical
+    ax.view_init(125, -90, 0)
+
+    vmin = np.min([np.min(aux) for aux in random_field])
+    vmax = np.max([np.max(aux) for aux in random_field])
+
+    for i, coord in enumerate(coordinates):
+        x, y, z = coord[:, 0], coord[:, 1], coord[:, 2]
+        ax.scatter(x, y, z, c=random_field[i], vmin=vmin, vmax=vmax, cmap="viridis", edgecolors=None, marker="s")
+
+    ax.set_xlabel('x coordinate')
+    ax.set_ylabel('y coordinate')
+    ax.set_zlabel('z coordinate')
+
+    cax = ax.inset_axes([1.1, 0., 0.05, 1])
+    norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
+    fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="viridis"), ax=ax, cax=cax)
+    fig.suptitle(title)
+    plt.savefig(os.path.join(output_folder, output_name))
+    plt.close()
+
+
+def plot2D(coordinates: list, random_field: list, title: str = "Random Field",
+           output_folder = "./", output_name: str = "random_field.png"):
+    """
+    Plot 2D random field
+
+    Parameters
+    ----------
+    coordinates : list
+        List of coordinates of the random field
+    random_field : list
+        List of random field values
+    title : str
+        Title of the plot
+    output_folder : str
+        Output folder
+    output_name : str
+        Output fine name
+    """
+
+    # create output folder
+    if not os.path.exists(output_folder):
+        os.makedirs(output_folder)
+
+    # make plot
+    fig, ax = plt.subplots(figsize=(6, 5))
+    ax.set_position([0.1, 0.1, 0.7, 0.8])
+
+    vmin = np.min([np.min(aux) for aux in random_field])
+    vmax = np.max([np.max(aux) for aux in random_field])
+
+    for i, coord in enumerate(coordinates):
+        x, y = coord[:, 0], coord[:, 1]
+        ax.scatter(x, y, c=random_field[i], vmin=vmin, vmax=vmax, cmap="viridis", edgecolors=None, marker="s")
+
+    ax.set_xlabel('x coordinate')
+    ax.set_ylabel('y coordinate')
+
+    cax = ax.inset_axes([1.1, 0., 0.05, 1])
+    norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
+    fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="viridis"), ax=ax, cax=cax)
+    fig.suptitle(title)
+    plt.savefig(os.path.join(output_folder, output_name))
+    plt.close()

random_fields-1.0.1.dist-info/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023-2025, StemVibrations
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

random_fields-1.0.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.2
+Name: random_fields
+Version: 1.0.1
+Summary: Random fields on unstructured grids
+Author: attr: random_fields.__author__
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Unix
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: matplotlib>=3.9.3
+Requires-Dist: gstools>=1.6.0
+Provides-Extra: testing
+Requires-Dist: pytest>=7.4.2; extra == "testing"
+Requires-Dist: pytest-cov>=4.1.0; extra == "testing"
+Requires-Dist: tox>=4.4; extra == "testing"
+Provides-Extra: docs
+Requires-Dist: Sphinx==6.2.1; extra == "docs"
+Requires-Dist: sphinx-rtd-theme==1.2.2; extra == "docs"
+
+# RandomFields
+![Tests](https://github.com/StemVibrations/RandomFields/actions/workflows/tests.yml/badge.svg)
+[![codecov](https://codecov.io/gh/StemVibrations/RandomFields/graph/badge.svg?token=KNV140ZHKQ)](https://codecov.io/gh/StemVibrations/RandomFields)
+
+# Random Fields
+
+Python package to generate random fields in 2D or 3D on unstructured grids.
+
+## Background information
+The random fields are generated using [gstools](https://geostat-framework.readthedocs.io/en/latest/).
+
+Currently, the following covariance models are available:
+- Gaussian
+- Exponential
+- Matern
+- Linear
+
+## Installation
+
+To install the package, run the following command in the terminal:
+```bash
+pip install git+https://github.com/StemVibrations/RandomFields
+```
+
+# Tutorial
+## Example in 2D
+
+In this example we generate a random field on a 2D regular grid.
+
+First you need to import the packages:
+
+```python
+import numpy as np
+from random_fields.generate_field import RandomFields, ModelName
+from random_fields.utils import plot2D
+```
+
+Then you need to define the grid:
+
+```python
+x = np.linspace(0, 100, 50)
+y = np.linspace(0, 50, 50)
+
+x, y = np.meshgrid(x, y)
+```
+
+In this example we create a mesh of 50x50 points between 0 and 100 in x and 0 and 50 in y direction.
+
+Then we define the random field properties:
+
+```python
+nb_dimensions = 2
+mean = 10
+variance = 2
+vertical_scale_fluctuation = 10
+anisotropy = [1]
+angle = [0]
+model_rf = ModelName.Gaussian
+```
+
+In this example we use a Gaussian covariance model.
+
+Then we create the random field:
+
+```python
+rf = RandomFields(model_rf, nb_dimensions, mean, variance, vertical_scale_fluctuation, anisotropy, angle, seed=14)
+rf.generate(np.array([x.ravel(), y.ravel()]).T)
+```
+
+To visualise the results you can run:
+
+```python
+plot2D([np.array([x.ravel(), y.ravel()]).T], [rf.random_field], title="Random Field", output_folder="./", output_name="random_field.png")
+```
+
+The result is the following random field:
+
+![Random field 2D](./docs/static/random_field.png)
+
+## Example in 3D
+
+In this example we generate a random field on a 3D regular grid.
+
+First you need to import the packages:
+
+```python
+import numpy as np
+from random_fields.generate_field import RandomFields, ModelName
+from random_fields.utils import plot3D
+```
+
+Then you need to define the grid:
+
+```python
+x = np.linspace(0, 100, 50)
+y = np.linspace(0, 50, 50)
+z = np.linspace(0, 25, 25)
+
+x, y, z = np.meshgrid(x, y, z)
+```
+In this example we create a mesh of 50x50x25 points between 0 and 100 in x, 0 and 50 in y direction and 0 and 25 in z direction.
+
+Then we define the random field properties:
+
+```python
+nb_dimensions = 3
+mean = 10
+variance = 2
+vertical_scale_fluctuation = 10
+anisotropy = [5, 5]
+angle = [0, 0]
+model_rf = ModelName.Gaussian
+```
+
+Then we create the random field:
+
+```python
+rf = RandomFields(model_rf, nb_dimensions, mean, variance, vertical_scale_fluctuation, anisotropy, angle, seed=14)
+rf.generate(np.array([x.ravel(), y.ravel(), z.ravel()]).T)
+```
+
+To visualise the results you can run:
+
+```python
+plot3D([np.array([x.ravel(), y.ravel(), z.ravel()]).T], [rf.random_field], title="Random Field", output_folder="./", output_name="random_field_3D.png")
+
+```
+The result is the following random field:
+
+![Random field 3D](./docs/static/random_field_3D.png)

random_fields-1.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+random_fields/__init__.py,sha256=e3S0EcDGJlWIp2hddSFjvt633jfeZ4W7VyAeLpfTWVM,37
+random_fields/__version__.py,sha256=DLIwjEWAWM3KBFCJ_Q00fL6GY1GlsiYH0pveSBIDxww,85
+random_fields/generate_field.py,sha256=0C4h9viPoj7o4szOBzI7WGzmPb2SC-YH5_C72JJ2w94,3397
+random_fields/utils.py,sha256=dBMqWMe0knF-Leb0aCXCqztGeOYx5FnukOQyPWIbfPo,2967
+random_fields-1.0.1.dist-info/LICENSE,sha256=WbcTzZtVX4H8BLF_mD2BtvCL8oh43TQtyugBiPKVDwo,1506
+random_fields-1.0.1.dist-info/METADATA,sha256=PXgQ1zIBAgF9v57W4g6csZ9kyN0R30wdHM8i8rk3RL8,4073
+random_fields-1.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+random_fields-1.0.1.dist-info/top_level.txt,sha256=yFqhrKXL6hMrmI_OAUg9EBy5DvJsOQYBpLqqGdqL2zE,14
+random_fields-1.0.1.dist-info/RECORD,,

random_fields-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

random_fields-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+random_fields