PyCosmoMMF 0.5.0__tar.gz → 1.0.1__tar.gz

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycosmommf
-Version: 0.5.0
+Version: 1.0.1
 Summary: A package for identifying structures in the cosmic web.
 Project-URL: Homepage, https://github.com/James11222/pycosmommf
 Project-URL: Bug Tracker, https://github.com/James11222/pycosmommf/issues
@@ -64,6 +64,7 @@ Description-Content-Type: text/markdown
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
+[![DOI](https://zenodo.org/badge/770792459.svg)](https://doi.org/10.5281/zenodo.14876495)
 
 [![codecov](https://codecov.io/gh/James11222/PyCosmoMMF/graph/badge.svg?token=UCHHHXEV2D)](https://codecov.io/gh/James11222/PyCosmoMMF)
 [![PyPI version][pypi-version]][pypi-link]

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/README.md

@@ -2,6 +2,7 @@
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
+[![DOI](https://zenodo.org/badge/770792459.svg)](https://doi.org/10.5281/zenodo.14876495)
 
 [![codecov](https://codecov.io/gh/James11222/PyCosmoMMF/graph/badge.svg?token=UCHHHXEV2D)](https://codecov.io/gh/James11222/PyCosmoMMF)
 [![PyPI version][pypi-version]][pypi-link]

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/docs/basic_usage.md

@@ -46,7 +46,7 @@ density_field = np.load("path/to/density_field.npy")
 Rs = [sqrt(2) ** n for n in range(10)]  # smoothing scales
 
 max_signatures = PyCosmoMMF.maximum_signature(
-    Rs, density_field, alg="NEXUSPLUS"
+    Rs, density_field, algorithm="NEXUSPLUS"
 )  # compute maximum signatures
 ```
 
@@ -67,18 +67,13 @@ output of this can be seen below
 
 We then have the option of running the tagging scheme a few different ways. The
 first important argument in `calc_structure_bools()` besides the `density_field`
-and the `max_signatures` arrays is the `verbose_flag`. When
-
-set to `True` the code gives a lot more information and provides a few plots.
-This is best turned on when
-
-debugging the code. When `verbose_flag` is turned on there are 4 additional
-outputs to the `calc_structure_bools()`
-
-function: `S_fil, dM2_fil, S_wall, dM2_wall` which can be used to make the mass
-change curves for filaments and
-
-walls.
+and the `max_signatures` arrays is the `verbose_flag`. When set to `True` the
+code gives a lot more information and provides a few plots. This is best turned
+on when debugging the code. When `verbose_flag` is turned on there is an
+additional output to the `calc_structure_bools()` function: `summary_data` which
+is a dictionary containing all the relevant extra information one might need. It
+can be used to make the mass change curves for filaments and walls. Consult the
+API Docs tab for a detailed summary of what is inside `summary_data`.
 
 **_Verbose Flag On:_**
 
@@ -86,8 +81,8 @@ walls.
 verbose_flag = True  # or False
 
 
-clusbool, filbool, wallbool, voidbool, S_fil, dM2_fil, S_wall, dM2_wall = (
-    PyCosmoMMF.calc_structure_bools(density_field, max_signatures, verbose_flag)
+clusbool, filbool, wallbool, voidbool, summary_data = PyCosmoMMF.calc_structure_bools(
+    density_field, max_signatures, verbose_flag
 )  # tag structures
 ```
 
@@ -125,11 +120,13 @@ clusbool, filbool, wallbool, voidbool = PyCosmoMMF.calc_structure_bools(
 ```
 
 Another important optional argument in the `calc_structure_bools()` function is
-`Δ`. The default value is `Δ = 370` as used in
+`overdensity_threshold`. The default value is `overdensity_threshold = 370` as
+used in
 [Cautun et al. 2013](https://academic.oup.com/mnras/article/429/2/1286/1038906)
-but other values can be 200 or 500 corresponding to `R_200` or `R_500`. `Δ` is
-the overdensity parameter, when clusters achieve a density greater than this
-value, they are thought to be virialized/collapsed.
+but other values can be 200 or 500 corresponding to `R_200` or `R_500`.
+`overdensity_threshold` is the overdensity parameter Δ, when clusters achieve an
+average overdensity greater than this value, they are thought to be
+virialized/collapsed.
 
 The boolean filters for each structure type produced by `calc_structure_bools()`
 can be used to tag structures within a density field, the results of this can be

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/pyproject.toml

@@ -124,6 +124,7 @@ ignore = [
   "PLR09",    # Too many <...>
   "PLR2004",  # Magic value used in comparison
   "ISC001",   # Conflicts with formatter
+  "RUF001",   # allow usage of `ρ` symbol in docstrings
 ]
 isort.required-imports = ["from __future__ import annotations"]
 

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/src/pycosmommf/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.5.0'
-__version_tuple__ = version_tuple = (0, 5, 0)
+__version__ = version = '1.0.1'
+__version_tuple__ = version_tuple = (1, 0, 1)

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/src/pycosmommf/filter.py

@@ -8,19 +8,19 @@ jit_compiler = nb.njit(parallel=True, fastmath=True)
 
 def wavevectors3D(dims, box_size=(2 * np.pi, 2 * np.pi, 2 * np.pi)):
     """
-    Returns the wavevectors for a 3D grid of dimensions `dims` and box size `box_size`.
-
-    Parameters
-    ----------
-    dims : tuple
-        The dimensions of the grid.
-    box_size : tuple
-        The size of the box in each dimension.
-
-    Returns
-    -------
-    kx, ky, kz : tuple
-        The wavevectors in each dimension.
+    Returns the wavevectors for a 3D grid of dimensions ``dims`` and box size ``box_size``.
+
+    Args:
+        dims (:obj:`tuple`):
+            The dimensions of the grid ``(nx, ny, nz)``.
+        box_size (:obj:`tuple`, optional):
+            The size of the box in each dimension ``(Lx, Ly, Lz)``. Defaults to ``(2π, 2π, 2π)``.
+
+    Returns:
+        (tuple): a tuple containing:
+            - **kx** (:obj:`np.ndarray`): The wavevector in the x-direction.
+            - **ky** (:obj:`np.ndarray`): The wavevector in the y-direction.
+            - **kz** (:obj:`np.ndarray`): The wavevector in the z-direction.
     """
     sample_rate = 2 * np.pi * (np.array(dims) / box_size)
     kx = (np.fft.fftfreq(dims[0], 1 / sample_rate[0]) * (2 * np.pi / dims[0])).astype(
@@ -40,17 +40,14 @@ def kspace_gaussian_filter(R_S, kv):  # pragma: no cover
     """
     create a Gaussian filter in k-space.
 
-    Parameters
-    ----------
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    filter_k : array
-        The filter in k-space.
+    Args:
+        R_S (:obj:`float`):
+            The smoothing scale.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension, each a ``1D float np.ndarray``.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The filter in k-space.
     """
     kx, ky, kz = kv
     nx, ny, nz = len(kx), len(ky), len(kz)
@@ -69,17 +66,14 @@ def kspace_top_hat_filter(R_S, kv):  # pragma: no cover
     """
     create a top-hat filter in k-space.
 
-    Parameters
-    ----------
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    filter_k : array
-        The filter in k-space.
+    Args:
+        R_S (:obj:`float`):
+            The smoothing scale.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The filter in k-space.
     """
 
     kx, ky, kz = kv
@@ -106,19 +100,16 @@ def smooth_top_hat(f, R_S, kv):
     """
     apply a top-hat filter to a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     GF = kspace_top_hat_filter(R_S, kv)
     f_Rn = np.real(np.fft.ifftn(GF * np.fft.fftn(f)))
@@ -130,19 +121,16 @@ def smooth_gauss(f, R_S, kv):
     """
     apply a Gaussian filter to a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     GF = kspace_gaussian_filter(R_S, kv)
     f_Rn = np.real(np.fft.ifftn(GF * np.fft.fftn(f)))
@@ -154,19 +142,16 @@ def smooth_loggauss(f, R_S, kv):
     """
     apply a Gaussian filter to the log of a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     # Get filter in Fourier space
     GF = kspace_gaussian_filter(R_S, kv)

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/src/pycosmommf/hessian.py

@@ -10,19 +10,17 @@ def fast_hessian_from_smoothed(f_Rn, R_S, kv):
     """
     Compute the hessian matrix of the smoothed field f_Rn.
 
-    Parameters
-    ----------
-    f_Rn : 3D array
-        The smoothed field.
-    R_S : float
-        The smoothing scale.
-    kv : 3D array
-        The wavevectors.
-
-    Returns
-    -------
-    hessian : 3D array
-        The hessian matrix.
+    Args:
+        f_Rn (:obj:`3D float np.ndarray`):
+            The smoothed field in real space.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`4D float np.ndarray`): The hessian matrix of the smoothed field.
+        The shape is ``(nx, ny, nz, 6)``, where ``nx, ny, nz`` are the dimensions of ``f_Rn``.
     """
 
     f_Rn_hat = np.fft.fftn(f_Rn)

{pycosmommf-0.5.0 → pycosmommf-1.0.1}/src/pycosmommf/signatures.py

@@ -14,15 +14,15 @@ def signatures_from_hessian(hessian):  # pragma: no cover
     """
     Function to calculate the signatures from a given hessian.
 
-    Parameters
-    ----------
-    hessian : 4D array
-        The hessian matrix.
-
-    Returns
-    -------
-    sigs : 4D array
-        The signatures.
+    Args:
+        hessian (:obj:`4D float np.ndarray`):
+            The hessian matrix of the smoothed field, with shape ``(nx, ny, nz, 6)``.
+
+    Returns:
+        (:obj:`4D float np.ndarray`): The signatures array with shape ``(nx, ny, nz, 3)``. Each signature corresponds to a different type of structure:
+            - ``sigs[..., 0]``: Cluster signature
+            - ``sigs[..., 1]``: Filament signature
+            - ``sigs[..., 2]``: Wall signature
     """
 
     hsize = hessian.shape[:3]
@@ -78,35 +78,34 @@ def signatures_from_hessian(hessian):  # pragma: no cover
     return sigs
 
 
-def maximum_signature(Rs, field, alg="NEXUSPLUS", eps=1e-8):
+def maximum_signature(Rs, density_cube, algorithm="NEXUSPLUS", eps=1e-8):
     """
     Compute the maximum signatures across all scales Rs.
 
-    Parameters
-    ----------
-    Rs : array
-        The scales.
-    field : 3D array
-        The field.
-    alg : string, optional
-        The algorithm to use. Can be either 'NEXUS' or 'NEXUSPLUS'.
-        Default is 'NEXUSPLUS'.
-    eps : float, optional
-        A small number to avoid division by zero errors and whatnot. Default is 1e-8.
-
-    Returns
-    -------
-    sigmax : 4D array
-        The maximum signatures.
+    Args:
+        Rs (:obj:`list` of :obj:`float`):
+            List of smoothing scales in units of voxels.
+        density_cube (:obj:`3D float np.ndarray`):
+            The 3D density field to analyze.
+        algorithm (:obj:`str`, optional):
+            The algorithm to use for smoothing. Can be either "NEXUS" or "NEXUSPLUS". Defaults to "NEXUSPLUS".
+        eps (:obj:`float`, optional):
+            Small value to avoid division by zero. Defaults to ``1e-8``.
+
+    Returns:
+        (:obj:`4D float np.ndarray`):
+            An array of signatures with shape ``(nx, ny, nz, 3)``, where ``nx, ny, nz`` are the dimensions of the input ``density_cube``.
+            The last dimension contains the signatures for clusters, filaments, and walls respectively.
     """
-    if alg not in ["NEXUS", "NEXUSPLUS"]:  # pragma: no cover
-        msg = "alg must be either 'NEXUS' or 'NEXUSPLUS'"
+
+    if algorithm not in ["NEXUS", "NEXUSPLUS"]:  # pragma: no cover
+        msg = "algorithm must be either 'NEXUS' or 'NEXUSPLUS'"
         raise ValueError(msg)
 
-    nx, ny, nz = field.shape
+    nx, ny, nz = density_cube.shape
 
     # Make sure the field has no 0 values
-    field = field + eps
+    density_cube = density_cube + eps
 
     # Calculate wave vectors for our field
     wave_vecs = wavevectors3D((nx, ny, nz))
@@ -125,10 +124,10 @@ def maximum_signature(Rs, field, alg="NEXUSPLUS", eps=1e-8):
                         )
 
     for R in Rs:
-        if alg == "NEXUS":
-            f_Rn = smooth_gauss(field, R, wave_vecs)
-        elif alg == "NEXUSPLUS":
-            f_Rn = smooth_loggauss(field, R, wave_vecs)
+        if algorithm == "NEXUS":
+            f_Rn = smooth_gauss(density_cube, R, wave_vecs)
+        elif algorithm == "NEXUSPLUS":
+            f_Rn = smooth_loggauss(density_cube, R, wave_vecs)
 
         H_Rn = fast_hessian_from_smoothed(f_Rn, R, wave_vecs)