Merge pull request #20 from amepproject/release-1.0.x

merge release 1.0.x into main
amepproject · Apr 22, 2024 · 7491673 · 7491673
2 parents 88176de + 6074128
commit 7491673
Show file tree

Hide file tree

Showing 15 changed files with 131 additions and 75 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,21 @@
 All notable changes to **AMEP** will be documented in this file. **AMEP** 
 adheres to [semantic versioning](https://semver.org/).
 
+## AMEP 1.0.1 (22 Apr 2024)
+
+### Bug fixes:
+
+* bug related to physical times not getting updated when timestep of trajectory object was changed fixed (LH)
+* incompatibility with Python 3.12 related to distutils fixed (LH)
+* bug in watershed cluster detection related to bubble detection fixed (KS)
+* some minor issues in documentation fixed (LH)
+
+### Contributors:
+
+* Lukas Hecht (LH)
+* Kai Luca Spanheimer (KS)
+
+
 ## AMEP 1.0.0  (21 Mar 2024)
 
 This is the first public version of **AMEP**. It fully integrates the analysis 

diff --git a/README.md b/README.md
@@ -2,6 +2,9 @@
 [![GitHub Discussions](https://img.shields.io/github/discussions/amepproject/amep)](https://github.com/amepproject/amep/discussions)
 ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Famepproject%2Famep%2Fmain%2Fpyproject.toml)
 [![Static Badge](https://img.shields.io/badge/documentation-amepproject.de-blue)](https://amepproject.de)
+[![Pepy Total Downlods](https://img.shields.io/pepy/dt/amep?label=pypi%7Cdownloads)](https://pypi.org/project/amep/)
+[![Conda Downloads](https://img.shields.io/conda/d/conda-forge/amep)](https://anaconda.org/conda-forge/amep)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/amepproject/amep/test.yml?label=pipeline)](https://github.com/amepproject/amep/actions)
 
 <center><img src="https://raw.githubusercontent.com/amepproject/amep/main/doc/source/_static/images/amep-logo_v2.png" alt="amep logo" width="200" height="200"/></center>
 
@@ -83,11 +86,29 @@ simulation data.
 
 # Installation
 
-The **AMEP** library can be installed either via `pip` or by manually adding 
-the `amep` directory to your Python path. Installation via `pip` is 
+The **AMEP** library can be installed via `pip`, `conda`, or by manually adding 
+the `amep` directory to your Python path. Installation via `pip` or `conda` is 
 recommended. To use all plot animation features, please additionally install 
 FFmpeg (https://ffmpeg.org/) on your machine (see below).
 
+## Installation via pip
+
+**AMEP** can be simply installed from [PyPI](https://pypi.org/project/amep/) 
+via 
+
+```bash
+pip install amep
+```
+
+## Installation via conda
+
+**AMEP** can be simply installed from 
+[conda-forge](https://anaconda.org/conda-forge/amep) via 
+
+```bash
+conda install conda-forge::amep
+```
+
 ## Manual installation
 
 Before installing **AMEP** manually, ensure that your Python environment 
@@ -114,16 +135,6 @@ to the `.bash_profile` file (Linux only). If you use the Anaconda distribution,
 you can alternatively add the `amep` directory to `Lib/site-packages` in the 
 Anaconda installation path.
 
-## Installation via pip
-
-**AMEP** can be simply installed using `pip`: 
-
-```bash
-pip install amep
-```
-
-The installation via `pip` is recommended.
-
 ## FFmpeg
 
 **AMEP** provides the possibility to animate plots and trajectories. 
@@ -216,10 +227,13 @@ COORDINATES: X Y Z
 <X_1> <Y_1> <Z_1>
 ...
 ```
-All data that varies in time is to be put into files named `field_<index>.txt`. 
-The index should increase with time, i.e., the file `field_1000.txt` should 
-contain the data of the continuum simulation at timestep 1000. The data files 
-should have the folowing form:
+All data that varies in time is to be put into files named `dump<index>.txt`. 
+The index should increase with time, i.e., the file `dump1000.txt` should 
+contain the data of the continuum simulation at timestep 1000, and the prefix 
+`dump` is user-defined and can be changed (if it is changed, the new naming 
+convention has to be specified with the keyword `dumps` in `amep.load.traj`, 
+e.g., for files named `field_100.txt`, `field_200.txt`, ..., use 
+`dumps='field_*.txt'`). The data files should have the following form:
 ```
 TIMESTEP:
 <Simulation timestep>

diff --git a/amep/_version.py b/amep/_version.py
@@ -20,4 +20,4 @@
 """
 AMEP version number.
 """
-__version__ = "1.0.0"
+__version__ = "1.0.1"
diff --git a/amep/base.py b/amep/base.py
@@ -348,6 +348,7 @@ def dt(self):
     def dt(self,x):
         with h5py.File(os.path.join(self.savedir, self.filename), 'a') as root:
             root['params'].attrs['dt'] = x
+        self.times = self.steps*x
 
     @property
     def d(self):

diff --git a/amep/continuum.py b/amep/continuum.py
@@ -539,12 +539,15 @@ def identify_clusters(
         The scale of the field. This is needed to improve the segmentation
         done in the watershed algorithm. This keyword is ignored when using
         `method='threshold'`. The default is 1.0.
+        Can also be set to negative value to make bubble detection
+        accesible.
     pbc : bool, optional
         Whether to use periodic boundary conditions. Default is True.
     cutoff: float, optional
         Caps the highest field values to the ratio of the data extent. Default
-        value 1.0 means no cut, 0.9 means the highest 10% of the field get cut
-        off. Needed for clusters with multiple local minima. Combats
+        value 1.0 means no cut, 0.9 means the highest and lowest 10%
+        of the field get cut off.
+        Needed for clusters with multiple local minima. Combats
         oversegmentation. This keyword is ignored when using
         `method='threshold'`. The default is 1.0.
     threshold : float, optional
@@ -608,7 +611,8 @@ def identify_clusters(
             minimum = np.min(dfield)
             maximum = np.max(dfield)
             upper_cut = maximum-(1-cutoff)*(maximum-minimum)
-            dfield_scaled = (np.clip(dfield, minimum, upper_cut) * scale).astype(int)
+            lower_cut = minimum+(1-cutoff)*(maximum-minimum)
+            dfield_scaled = (np.clip(dfield, lower_cut, upper_cut) * scale).astype(int)
 
             # apply watershed
             labels = watershed(-dfield_scaled, markers=None, mask=dfield_scaled)

diff --git a/amep/evaluate.py b/amep/evaluate.py
@@ -2175,10 +2175,11 @@ def __init__(
         trajectory does not contain the radii of the particles, you can
         add the radius (here 0.5) to the trajectory using
         
-        ```python
-        for frame in traj:
-            frame.add_data("radius", 0.5*np.ones(len(frame.n())))
-        ```
+        .. code-block:: python
+
+            for frame in traj:
+                frame.add_data("radius", 0.5*np.ones(len(frame.n())))
+
 
         Parameters
         ----------

diff --git a/amep/plot.py b/amep/plot.py
@@ -36,6 +36,7 @@
 from os.path import abspath, dirname, join
 from pathlib import Path
 import warnings
+import shutil
 import numpy as np
 import matplotlib as mpl
 import matplotlib.pyplot as plt
@@ -48,7 +49,6 @@
 from matplotlib.colors import to_rgba, ListedColormap
 from matplotlib.animation import FuncAnimation
 from tqdm.autonotebook import tqdm
-from distutils.spawn import find_executable
 
 from .trajectory import FieldTrajectory, ParticleTrajectory
 from .base import get_module_logger
@@ -71,17 +71,19 @@ def matplotlib_plot_defaults():
 
 def style(style_name: str = "", mpl_default: bool = False) -> None:
     r'''
-    Set the locations of major and minor ticks.
+    Set the plot style.
 
     Parameters
     ----------
     style_name : str, optional
-        Specifies the name of the style to apply.
-
+        Specifies the name of the style to apply. Apart from the Matplotlib
+        styles, one can choose the AMEP styles `'amep_latex'` and 
+        `'amep_standard'`. The AMEP styles are used per default when AMEP is
+        imported.
     mpl_default : bool, optional
         Determines whether to apply a style or revert
-        to the default pyplot style.
-        The default is False.
+        to the default pyplot style. The default is False.
+
     Returns
     -------
     None.
@@ -106,7 +108,7 @@ def amep_plot_defaults():
     -------
     None.
     '''
-    if find_executable('latex'):
+    if shutil.which('latex'):
         style('amep_latex')
     else:
         _log.info(

diff --git a/amep/reader.py b/amep/reader.py
@@ -204,9 +204,6 @@ def __init__(
             first = int(self.start*len(files))  # first dump file index
             last  = int(self.stop*len(files))   # last dump file index
 
-            # get time step from log file
-            self.dt = self.__get_timestep_from_logfile()
-
             # dump files to load
             files = files[first:last:self.nth]
 
@@ -530,7 +527,8 @@ def __init__(
                     )
 
             self.steps = steps
-            self.times = steps*self.dt
+            # get time step from log file (this also sets self.times)
+            self.dt = self.__get_timestep_from_logfile()
             self.d = d
         except Exception as e:
             os.remove(os.path.join(savedir, "#temp#"+trajfile))
@@ -701,19 +699,6 @@ def __init__(
         self.__time_warning = False
         self.__verbose = verbose
 
-        # set time step
-        if timestep is not None:
-            self.dt = timestep
-        else:
-            self.dt = 1.0
-            self.__log.warning(
-                "Timestep not set. "\
-                "Use default timestep of 1.0. This value is ignored if the "\
-                "'TIME' is specified in your data files. Please check the "\
-                "required continuum data format for more details. "\
-                "The timestep can be set manually by traj.dt=<dt>."
-            )
-
         try:
             # get data files
             fields = sorted(glob.glob(os.path.join(self.directory,
@@ -744,15 +729,28 @@ def __init__(
 
             d = self.__set_grid(os.path.join(self.directory, gridfile), delimiter)
             for index, field_file in enumerate(tqdm(fields)):
-                # step = self.__set_field(os.path.join(self.directory,field_file), index, delimiter)
                 step, time = self.__set_field(field_file, index, delimiter)
                 steps[index] = step
                 if time == 0.0:
-                    time = step*self.dt
+                    # use dt=1
+                    time = step
                 times[index] = time
             self.steps = steps
-            self.times = times
+            # set time step
+            if timestep is not None:
+                self.dt = timestep
+            else:
+                self.times = times
+                self.__log.warning(
+                    "Timestep not set. "\
+                    "Use default timestep of 1.0. This value is ignored if the "\
+                    "'TIME' is specified in your data files. Please check the "\
+                    "required continuum data format for more details. "\
+                    "The timestep can be set manually by traj.dt=<dt>."
+                )
+            # set dimension
             self.d = d
+
         except Exception as err:
             os.remove(os.path.join(savedir, "#temp#"+trajfile))
             if "ContinuumReader: no dump files in this directory." in err.args[0]:

diff --git a/amep/spatialcor.py b/amep/spatialcor.py
@@ -1108,6 +1108,7 @@ def pcf_angle(
     Examples
     --------
     >>> import amep
+    >>> import numpy as np
     >>> traj = amep.load.traj("../examples/data/lammps.h5amep")
     >>> frame = traj[-1]
     >>> grt, rt, theta = amep.spatialcor.pcf_angle(
@@ -1116,8 +1117,8 @@ def pcf_angle(
     ... )
     >>> X = rt*np.cos(theta)
     >>> Y = rt*np.sin(theta)
-    >>> fig, axs = amep.plot.new(figsize=(3.7,3))
-    >>> mp = amep.plot.field(axs, grt, X, Y)
+    >>> fig, axs = amep.plot.new(figsize=(3.8,3))
+    >>> mp = amep.plot.field(axs, grt.T, X, Y)
     >>> cax = amep.plot.add_colorbar(
     ...     fig, axs, mp, label=r'$g(\Delta x, \Delta y)$'
     ... )
@@ -1128,6 +1129,10 @@ def pcf_angle(
     >>> fig.savefig('./figures/spatialcor/spatialcor-pcf_angle.png')
     >>> 
     
+    .. image:: /_static/images/spatialcor/spatialcor-pcf_angle.png
+      :width: 400
+      :align: center
+    
     '''
     # get box length
     box = box_boundary[:,1]-box_boundary[:,0]

diff --git a/doc/source/_static/images/spatialcor/spatialcor-pcf_angle.png b/doc/source/_static/images/spatialcor/spatialcor-pcf_angle.png
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -9,7 +9,7 @@
 project = 'AMEP'
 copyright = '2023-2024, Lukas Hecht, Kay-Robert Dormann, Kai Luca Spanheimer'
 author = 'Lukas Hecht, Kay-Robert Dormann, Kai Luca Spanheimer'
-release = '1.0.0'
+release = '1.0.1'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

diff --git a/doc/source/datastructures/field_data.rst b/doc/source/datastructures/field_data.rst
@@ -21,10 +21,13 @@ it should have the following form::
    <X_1> <Y_1> <Z_1>
    ...
 
-All data that varies in time is to be put into files named `field_<index>.txt`. 
-The index should increase with time, i.e., the file `field_1000.txt` should 
-contain the data of the continuum simulation at timestep 1000. The data files 
-should have the folowing form::
+All data that varies in time is to be put into files named `dump<index>.txt`. 
+The index should increase with time, i.e., the file `dump1000.txt` should 
+contain the data of the continuum simulation at timestep 1000, and the prefix 
+`dump` is user-defined and can be changed (if it is changed, the new naming 
+convention has to be specified with the keyword `dumps` in `amep.load.traj`, 
+e.g., for files named `field_100.txt`, `field_200.txt`, ..., use 
+`dumps='field_*.txt'`). The data files should have the following form::
 
    TIMESTEP:
    <Simulation timestep>

diff --git a/doc/source/gettingstarted/installation.rst b/doc/source/gettingstarted/installation.rst
@@ -2,10 +2,34 @@
 Installation
 ============
 
-The **AMEP** library can be installed either via ``pip`` or by manually adding the 
-``amep`` directory to your Python path. Installation via ``pip`` is recommended.
-To use all plot animation features, please additionally install FFmpeg 
-(https://ffmpeg.org/) on your machine (see below).
+The **AMEP** library can be installed via ``pip``, ``conda``, or by manually 
+adding the ``amep`` directory to your Python path. Installation via ``pip`` or 
+``conda`` is recommended. To use all plot animation features, please 
+additionally install FFmpeg (https://ffmpeg.org/) on your machine (see below).
+
+--------------------
+Installation via pip
+--------------------
+
+**AMEP** can be simply installed from `PyPI <https://pypi.org/project/amep/>`_ 
+via 
+
+.. code-block:: bash
+
+    pip install amep
+
+
+----------------------
+Installation via conda
+----------------------
+
+**AMEP** can be simply installed from 
+`conda-forge <https://anaconda.org/conda-forge/amep>`_ via 
+
+.. code-block:: bash
+
+    conda install conda-forge::amep
+
 
 -------------------
 Manual installation
@@ -31,17 +55,6 @@ Alternatively, you can add the path permanently to your Python path by adding th
 to the ``.bash_profile file`` (Linux only). If you use the Anaconda distribution,
 you can alternatively add the ``amep`` directory to ``Lib/site-packages`` in the Anaconda installation path.
 
---------------------
-Installation via pip
---------------------
-
-**AMEP** can be simply installed via pip:
-
-.. code-block:: bash
-
-    pip install amep
-
-The installation via ``pip`` is recommended.
 
 ------
 FFmpeg