merge v0.5.0

precice · Oct 29, 2024 · 4cca701 · 4cca701
2 parents d6637c1 + 98d2485
commit 4cca701
Show file tree

Hide file tree

Showing 55 changed files with 1,872 additions and 385 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,8 @@
+<!-- Add a short description of your contribution here. Skip this if the title is self-explanatory -->
+
+Checklist:
+
+- [ ] I made sure that the CI passed before I ask for a review.
+- [ ] I added a summary of the changes (compared to the last release) in the `CHANGELOG.md`.
+- [ ] If necessary, I made changes to the documentation and/or added new content.
+- [ ] I will remember to squash-and-merge, providing a useful summary of the changes of this PR.
diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml
@@ -9,19 +9,21 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v1
       with:
         python-version: '3.x'
     - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel twine
+      uses: BSFishy/pip-action@v1
+      with:
+        packages: |
+          twine
+          build
     - name: Build and publish
       env:
         TWINE_USERNAME: __token__
         TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
       run: |
-        python setup.py sdist
+        pyproject-build
         twine upload dist/*
diff --git a/.github/workflows/run-adaptivity-test.yml b/.github/workflows/run-adaptivity-test.yml
@@ -23,26 +23,25 @@ jobs:
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python -m pip install --upgrade pip
-          pip install setuptools wheel
+          pip3 install --upgrade pip
 
       - name: Install Micro Manager
         working-directory: micro-manager
-        run: pip3 install --user .
+        run: pip3 install .
 
       - name: Run integration test with local adaptivity
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
         run: |
-          export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
-          python3 unit_cube.py & python3 run_micro_manager.py --config micro-manager-config-local-adaptivity.json
+          micro-manager-precice micro-manager-config-local-adaptivity.json &
+          python3 unit_cube.py
 
       - name: Run integration test with global adaptivity
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
         run: |
-          export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
-          python3 unit_cube.py & python3 run_micro_manager.py --config micro-manager-config-global-adaptivity.json
+          micro-manager-precice micro-manager-config-global-adaptivity.json &
+          python3 unit_cube.py
 
   adaptivity_unit_tests_serial:
     name: Run adaptivity unit tests in serial
@@ -59,8 +58,7 @@ jobs:
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python -m pip install --upgrade pip
-          pip install setuptools wheel
+          pip3 install --upgrade pip
 
       - name: Install Micro Manager
         working-directory: micro-manager
@@ -94,8 +92,7 @@ jobs:
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python -m pip install --upgrade pip
-          pip install setuptools wheel twine
+          pip3 install --upgrade pip
 
       - name: Install Micro Manager
         working-directory: micro-manager

diff --git a/.github/workflows/run-domain-decomposition-tests.yml b/.github/workflows/run-domain-decomposition-tests.yml
@@ -30,23 +30,27 @@ jobs:
       - name: Install Dependencies
         working-directory: micro-manager
         run: |
+          apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python -m pip install --upgrade pip
-          pip install setuptools wheel twine
+          pip3 install --upgrade pip
 
       - name: Install micro-manager
         working-directory: micro-manager
-        run: pip3 install --user .
+        run: pip3 install .
 
-      - name: Run integration test (variant 1)
+      - name: Run integration test (2 processes)
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
-        run: mpiexec -n 2 --allow-run-as-root python3 run_micro_manager.py --config micro-manager-config-parallel-1.json & python3 unit_cube.py
+        run: |
+          mpiexec -n 2 --allow-run-as-root micro-manager-precice micro-manager-config-parallel-1.json &
+          python3 unit_cube.py
 
-      - name: Run integration test (variant 2)
+      - name: Run integration test (6 processes)
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
-        run: mpiexec -n 6 --oversubscribe --allow-run-as-root python3 run_micro_manager.py --config micro-manager-config-parallel-2.json & python3 unit_cube.py
+        run: |
+          mpiexec -n 6 --oversubscribe --allow-run-as-root micro-manager-precice micro-manager-config-parallel-2.json &
+          python3 unit_cube.py
 
   domain_decomposition_unit_tests:
     name: Run domain decomposition unit tests
@@ -63,8 +67,7 @@ jobs:
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python -m pip install --upgrade pip
-          pip install setuptools wheel
+          pip3 install --upgrade pip
 
       - name: Install Micro Manager
         working-directory: micro-manager

diff --git a/.github/workflows/run-macro-micro-dummy.yml b/.github/workflows/run-macro-micro-dummy.yml
@@ -25,22 +25,26 @@ jobs:
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
           apt-get -qq install sudo
-          python -m pip install --upgrade pip
-          pip install setuptools wheel twine
+          pip3 install --upgrade pip
 
       - name: Install micro-manager
         working-directory: micro-manager
-        run: pip3 install --user .
+        run: |
+          pip3 install .
 
       - name: Run python macro-micro dummy
         timeout-minutes: 3
         working-directory: micro-manager/examples
-        run: python3 python-dummy/run_micro_manager.py --config micro-manager-config.json & python3 macro_dummy.py
+        run: |
+          micro-manager-precice micro-manager-python-config.json &
+          python3 macro_dummy.py
 
       - name: Run adaptive python macro-micro dummy
         timeout-minutes: 3
         working-directory: micro-manager/examples
-        run: python3 python-dummy/run_micro_manager.py --config micro-manager-adaptivity-config.json & python3 macro_dummy.py
+        run: |
+          micro-manager-precice micro-manager-python-adaptivity-config.json &
+          python3 macro_dummy.py
 
       - name: Run c++ macro-micro dummy
         timeout-minutes: 3
@@ -50,9 +54,12 @@ jobs:
           pip install pybind11
           c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) micro_cpp_dummy.cpp -o micro_dummy$(python3-config --extension-suffix)
           cd ../
-          python3 cpp-dummy/run_micro_manager.py --config micro-manager-config.json & python3 macro_dummy.py
+          micro-manager-precice micro-manager-cpp-config.json &
+          python3 macro_dummy.py
 
       - name: Run adaptive c++ macro-micro dummy
         timeout-minutes: 3
         working-directory: micro-manager/examples
-        run: python3 cpp-dummy/run_micro_manager.py --config micro-manager-adaptivity-config.json & python3 macro_dummy.py
+        run: |
+          micro-manager-precice micro-manager-cpp-adaptivity-config.json &
+          python3 macro_dummy.py
diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml
@@ -16,22 +16,48 @@ jobs:
         with:
           path: micro-manager
 
-      - name: Install Micro Manager and uninstall pyprecice
-        working-directory: micro-manager
+      - name: Install dependencies
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
+          pip3 install --upgrade pip
+
+      - name: Install Micro Manager and run micro_manager unit test
+        working-directory: micro-manager/
+        run: |
           pip3 install --user .
           pip3 uninstall -y pyprecice
+          cd tests/unit
+          python3 -m unittest test_micro_manager.py
+
+      - name: Install Micro Manager and run interpolation unit test
+        working-directory: micro-manager/
+        run: |
+          pip3 install --user .[sklearn]
+          pip3 uninstall -y pyprecice
+          cd tests/unit
+          python3 -m unittest test_interpolation.py
 
-      - name: Run micro_manager unit test
-        working-directory: micro-manager/tests/unit
-        run: python3 -m unittest test_micro_manager.py
+      - name: Install Micro Manager and run micro simulation crash unit test
+        working-directory: micro-manager/
+        run: |
+          pip3 install --user .
+          pip3 uninstall -y pyprecice
+          cd tests/unit
+          python3 -m unittest test_micro_simulation_crash_handling.py
 
-      - name: Run interpolation unit test
-        working-directory: micro-manager/tests/unit
-        run: python3 -m unittest test_interpolation.py
+      - name: Install Micro Manager and run HDF5 read and write unit tests
+        working-directory: micro-manager/
+        run: |
+          pip3 install --user .[snapshot]
+          pip3 uninstall -y pyprecice
+          cd tests/unit
+          python3 -m unittest test_hdf5_functionality.py
 
-      - name: Run micro simulation crash unit test
-        working-directory: micro-manager/tests/unit
-        run: python3 -m unittest test_micro_simulation_crash_handling.py
+      - name: Install Micro Manager and run snapshot_computation unit tests
+        working-directory: micro-manager/
+        run: |
+          pip3 install --user .[snapshot]
+          pip3 uninstall -y pyprecice
+          cd tests/unit
+          python3 -m unittest test_snapshot_computation.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,22 @@
 # Micro Manager changelog
 
-## latest
-
+## v0.5.0
+
+- Use absolute values to calculate normalizing factor for relative norms in adaptivity https://github.com/precice/micro-manager/pull/125
+- Add option to use only one micro simulation object in the snapshot computation https://github.com/precice/micro-manager/pull/123
+- Explicitly check if time window has converged using the API function `is_time_window_complete()` https://github.com/precice/micro-manager/pull/118
+- Add `MicroManagerSnapshot` enabling snapshot computation and storage of microdata in HDF5 format https://github.com/precice/micro-manager/pull/101
+- Make `sklearn` an optional dependency
+- Move the config variable `micro_dt` from the coupling parameters section to the simulation parameters section https://github.com/precice/micro-manager/pull/114
+- Set time step of micro simulation in the configuration, and use it in the coupling https://github.com/precice/micro-manager/pull/112
+- Add a base class called `MicroManager` with minimal API and member function definitions, rename the existing `MicroManager` class to `MicroManagerCoupling` https://github.com/precice/micro-manager/pull/111
+- Handle calling `initialize()` function of micro simulations written in languages other than Python https://github.com/precice/micro-manager/pull/110
+- Check if initial data returned from the micro simulation is the data that the adaptivity computation requires https://github.com/precice/micro-manager/pull/109
+- Use executable `micro-manager-precice` by default, and stop using the script `run_micro_manager.py` https://github.com/precice/micro-manager/pull/105
+- Make `initialize()` method of the MicroManager class public https://github.com/precice/micro-manager/pull/105
+- Optionally use initial macro data to initialize micro simulations https://github.com/precice/micro-manager/pull/104
+- Use `pyproject.toml` instead of `setup.py` to configure the build. Package name is now `micro_manager_precice` https://github.com/precice/micro-manager/pull/84
+- Add handling of crashing micro simulations https://github.com/precice/micro-manager/pull/85
 - Add switch to turn adaptivity on and off in configuration https://github.com/precice/micro-manager/pull/93
 
 ## v0.4.0

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@
 
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.05842/status.svg)](https://doi.org/10.21105/joss.05842)
 
-A tool to facilitate solving two-scale (macro-micro) coupled problems using the coupling library [preCICE](https://www.precice.org/).
+A tool to facilitate solving two-scale (macro-micro) coupled problems using the coupling library [preCICE](https://precice.org/).
 
 The main documentation is rendered on the [preCICE website](https://precice.org/tooling-micro-manager-overview.html).
 

diff --git a/docs/README.md b/docs/README.md
@@ -19,11 +19,17 @@ The Micro Manager couples many micro simulations with one macro simulation. This
 - ... running micro simulations in parallel using MPI.
 - ... adaptively activating and deactivating micro simulations based on a similarity calculation.
 
+The Micro Manager can also compute snapshots of micro simulations given macro input parameters in an offline manner without preCICE.
+
 ## Documentation
 
-To use the Micro Manager for a macro-micro coupling, your micro simulation code needs to be in a library format with a specific class name and functions with specific names. For a macro-micro coupled problem, the macro simulation code is coupled to preCICE directly. The section [couple your code](couple-your-code-overview.html) of the preCICE documentation gives more details on coupling existing codes. To setup a macro-micro coupled simulation using the Micro Manager, follow these steps:
+To use the Micro Manager for a macro-micro coupling, your micro simulation code needs to be in a library format with a specific class name and functions with specific names. For a macro-micro coupled problem, the macro simulation code is coupled to preCICE directly. The section [couple your code](couple-your-code-overview.html) of the preCICE documentation gives more details on coupling existing codes. To set up a macro-micro coupled simulation using the Micro Manager, follow these steps:
 
 - [Installation](tooling-micro-manager-installation.html)
 - [Preparing micro simulation](tooling-micro-manager-prepare-micro-simulation.html)
 - [Configuration](tooling-micro-manager-configuration.html)
 - [Running](tooling-micro-manager-running.html)
+
+To compute snapshots in an offline manner your simulation code also needs to be in a library format with a specific class name and functions with specific names. To set up a snapshot computation using the Micro Manager, follow these steps:
+
+- [Snapshot computation](tooling-micro-manager-snapshot-configuration.html)
diff --git a/docs/ReleaseGuide.md b/docs/ReleaseGuide.md
@@ -8,7 +8,7 @@ The release of the `micro-manager` repository is made directly from a release br
 
 2. If it is a real release, [open a Pull Request `main` <-- `micro-manager-v1.2.3`](https://github.com/precice/micro-manager/compare/main...main) named after the version (i.e. `Release v1.2.3`) and briefly describe the new features of the release in the PR description.
 
-3. Bump the version in the `CHANGELOG.md` and in `setup.py` on `micro-manager-v1.2.3`.
+3. Bump the version in the `CHANGELOG.md` on the branch `micro-manager-v1.2.3`.
 
 4. [Draft a new release](https://github.com/precice/micro-manager/releases/new) in the `Releases` section of the repository page in a web browser. The release tag needs to be the exact version number (i.e.`v1.2.3` or `v1.2.3rc1`, compare to [existing tags](https://github.com/precice/micro-manager/tags)). Use `@target:main`. Release title is also the version number (i.e. `v1.2.3` or `v1.2.3rc1`, compare to [existing releases](https://github.com/precice/micro-manager/tags)).
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -20,6 +20,7 @@ The Micro Manager is configured with a JSON file. An example configuration file
     },
     "simulation_params": {
         "macro_domain_bounds": [0.0, 1.0, 0.0, 1.0, 0.0, 1.0],
+        "micro_dt": 1.0
     },
     "diagnostics": {
       "output_micro_sim_solve_time": "True"
@@ -49,6 +50,7 @@ Parameter | Description
 `macro_domain_bounds`| Minimum and maximum bounds of the macro-domain, having the format `[xmin, xmax, ymin, ymax, zmin, zmax]` in 3D and `[xmin, xmax, ymin, ymax]` in 2D.
 Domain decomposition parameters | See section on [domain decomposition](#domain-decomposition). But default, the Micro Manager assumes that it will be run in serial.
 Adaptivity parameters | See section on [adaptivity](#adaptivity). By default, adaptivity is disabled.
+`micro_dt` | Initial time window size (dt) of the micro simulation.
 
 ## Diagnostics
 
@@ -162,6 +164,13 @@ The Micro Manager uses the output functionality of preCICE, hence these data set
 </participant>
 ```
 
+## Interpolate a crashed micro simulation
+
+If the optional dependency `sklearn` is installed, the Micro Manager will derive the output of a crashed micro simulation by interpolating outputs from similar simulations. To enable this, set
+`"interpolate_crash": "True"` in the `simulation_params` section of the configuration file.
+
+For more details on the interpolation see the [crash handling documentation](tooling-micro-manager-running.html/#what-happens-when-a-micro-simulation-crashes).
+
 ## Next step
 
 After creating a configuration file you are ready to [run the Micro Manager](tooling-micro-manager-running.html).
diff --git a/docs/installation.md b/docs/installation.md
@@ -17,7 +17,13 @@ The Micro Manager package has the name [micro-manager-precice](https://pypi.org/
 pip install --user micro-manager-precice
 ```
 
-Unless already installed, the dependencies will be installed by `pip` during the installation procedure. preCICE itself needs to be installed separately. If you encounter problems in the direct installation, see the [dependencies section](#required-dependencies) below.
+Unless already installed, the dependencies will be installed by `pip` during the installation procedure. To enable [crash handling by interpolation](tooling-micro-manager-running.html/#what-happens-when-a-micro-simulation-crashes), the optional dependency `sklearn` is required. To install `micro-manager-precice` with `sklearn`, run
+
+```bash
+pip install --user micro-manager-precice[sklearn]
+```
+
+preCICE itself needs to be installed separately. If you encounter problems in the direct installation, see the [dependencies section](#required-dependencies) and [optional dependency section](#optional-dependencies) below.
 
 ### Option 2: Install manually
 
@@ -31,6 +37,11 @@ Ensure that the following dependencies are installed:
 * [numpy](https://numpy.org/install/)
 * [mpi4py](https://mpi4py.readthedocs.io/en/stable/install.html)
 
+#### Optional dependencies
+
+* [sklearn](https://scikit-learn.org/stable/index.html)
+* [h5py](https://www.h5py.org/) (required for snapshot computations)
+
 #### Clone the Micro Manager
 
 ```bash
@@ -45,11 +56,7 @@ To install using `pip`, go to the directory `micro-manager/` and run
 pip install --user .
 ```
 
-To install using Python, go to the project directory `micro-manager/` and run
-
-```bash
-python setup.py install --user
-```
+Adding optional dependencies works as above by adding them after the dot, e.g. `.[sklearn]`.
 
 ## Get the latest development version