Merge pull request #88 from precice/micro-manager-v0.4.0

Release v0.4.0

.github/workflows/pythonpublish.yml

@@ -20,8 +20,8 @@ jobs:
         pip install setuptools wheel twine
     - name: Build and publish
       env:
-        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
       run: |
         python setup.py sdist
         twine upload dist/*

.github/workflows/run-adaptivity-test.yml

@@ -1,4 +1,4 @@
-name: Test adaptivity
+name: Test adaptivity functionality
 on:
   push:
     branches:
@@ -8,10 +8,10 @@ on:
     branches:
       - "*"
 jobs:  
-  integration_test:
-    name: Run integration test
+  adaptivity_integration_tests:
+    name: Run adaptivity integration tests
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -33,17 +33,21 @@ jobs:
       - name: Run integration test with local adaptivity
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
-        run: python3 unit_cube.py & python3 run_micro_manager.py --config micro-manager-config-local-adaptivity.json
+        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
 
-      - name: Run integration test serially with global adaptivity
+      - name: Run integration test with global adaptivity
         timeout-minutes: 3
         working-directory: micro-manager/tests/integration/test_unit_cube
-        run: python3 unit_cube.py & python3 run_micro_manager.py --config micro-manager-config-global-adaptivity.json
+        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
 
-  unit_tests_serial:
-    name: Run unit tests (serial variants)
+  adaptivity_unit_tests_serial:
+    name: Run adaptivity unit tests in serial
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v3
@@ -66,10 +70,10 @@ jobs:
         working-directory: micro-manager/tests/unit
         run: python3 -m unittest test_adaptivity_serial.py
 
-  unit_tests_parallel:
-    name: Run unit tests (parallel variants)
+  adaptivity_unit_tests_parallel:
+    name: Run adaptivity unit tests in parallel
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v3
@@ -85,21 +89,18 @@ jobs:
       - name: Use mpi4py
         uses: mpi4py/setup-mpi@v1
 
-      - name: Add user precice
-        run: useradd -m -s /bin/bash precice
-
       - 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
-          su -c "python -m pip install --upgrade pip" precice
-          su -c "pip install setuptools wheel twine" precice
+          python -m pip install --upgrade pip
+          pip install setuptools wheel twine
 
       - name: Install Micro Manager
         working-directory: micro-manager
-        run: su -c "pip3 install --user ." precice
+        run: pip3 install --user .
 
       - name: Run unit tests
         working-directory: micro-manager/tests/unit
-        run: su -c "mpiexec -n 2 python3 -m unittest test_adaptivity_parallel.py" precice
+        run: mpiexec -n 2 --allow-run-as-root python3 -m unittest test_adaptivity_parallel.py

.github/workflows/run-domain-decomposition-tests.yml

@@ -1,4 +1,4 @@
-name: Test domain decomposition
+name: Test functions in class DomainDecomposer
 on:
   push:
     branches:
@@ -8,10 +8,10 @@ on:
     branches:
       - "*"
 jobs:  
-  integration_test:
-    name: Run integration tests
+  domain_decomposition_integration_tests:
+    name: Run domain decomposition integration tests
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -27,39 +27,31 @@ jobs:
       - name: Use mpi4py
         uses: mpi4py/setup-mpi@v1
 
-      - name: Add user precice
-        run: useradd -m -s /bin/bash precice
-
       - name: Install Dependencies
         working-directory: micro-manager
         run: |
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          su -c "python -m pip install --upgrade pip" precice
-          su -c "pip install setuptools wheel twine" precice
+          python -m pip install --upgrade pip
+          pip install setuptools wheel twine
 
       - name: Install micro-manager
         working-directory: micro-manager
-        run: su -c "pip3 install --user ." precice
+        run: pip3 install --user .
 
       - name: Run integration test (variant 1)
         timeout-minutes: 3
-        working-directory: micro-manager/tests/integration
-        run: |
-          chown -R precice test_unit_cube/
-          cd test_unit_cube/
-          su -c "mpiexec -n 2 python3 run_micro_manager.py --config micro-manager-config-parallel-1.json & python3 unit_cube.py" precice
+        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
 
       - name: Run integration test (variant 2)
         timeout-minutes: 3
-        working-directory: micro-manager/tests/integration
-        run: |
-          cd test_unit_cube/
-          su -c "mpiexec -n 6 --oversubscribe python3 run_micro_manager.py --config micro-manager-config-parallel-2.json & python3 unit_cube.py" precice
+        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
 
-  unit_tests:
-    name: Run unit tests
+  domain_decomposition_unit_tests:
+    name: Run domain decomposition unit tests
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v3

.github/workflows/run-macro-micro-dummy.yml

@@ -11,7 +11,7 @@ jobs:
   run_dummy:
     name: Run dummy
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
 
       - name: Checkout Repository

.github/workflows/run-unit-tests.yml

@@ -1,4 +1,4 @@
-name: Run unit tests
+name: Run unit tests for functions in micro_manager.py
 on:
   push:
     branches:
@@ -10,7 +10,7 @@ on:
 jobs:
   unit-tests:
     runs-on: ubuntu-latest
-    container: precice/precice
+    container: precice/precice:nightly
     steps:
       - uses: actions/checkout@v3
         with:
@@ -21,8 +21,8 @@ jobs:
         run: |
           apt-get -qq update
           apt-get -qq install python3-dev python3-pip git python-is-python3 pkg-config
-          python3 -m pip install --user .
-          python3 -m pip uninstall -y pyprecice
+          pip3 install --user .
+          pip3 uninstall -y pyprecice
 
       - name: Run unit tests
         working-directory: micro-manager/tests/unit

CHANGELOG.md

@@ -1,6 +1,17 @@
 # Micro Manager changelog
 
-## latest
+## v0.4.0
+
+- Add note in the cpp-dummy that pickling support does not work due to no good way to pass the sim id to the new micro simulation instance [commit](https://github.com/precice/micro-manager/commit/0a82966676717a533aca9bffa4a110453158f29c)
+- Reintroduce initialize function in the micro simulation API https://github.com/precice/micro-manager/pull/79
+- Use Allgatherv instead of allgather when collecting number of micro simulations on each rank in initialization https://github.com/precice/micro-manager/pull/81
+- Remove the callable function `initialize()` from the micro simulation API [commit](https://github.com/precice/micro-manager/commit/bed5a4cc0f03b780da7f62b3f51ed1df2796588c)
+- Pass an ID to the micro simulation object so that it is aware of its own uniqueness https://github.com/precice/micro-manager/pull/66
+- Resolve bug which led to an error when global adaptivity was used with unequal number of simulations on each rank https://github.com/precice/micro-manager/pull/78
+- Make the `initialize()` method of the MicroManager class private https://github.com/precice/micro-manager/pull/77
+- Add reference paper via a CITATION.cff file [commit](https://github.com/precice/micro-manager/commit/6c08889c658c889d6ab5d0867802522585abcee5)
+- Add JOSS DOI badge [commit](https://github.com/precice/micro-manager/commit/2e3c2a4c77732f56a957abbad9e4d0cb64029725)
+- Update pyprecice API calls to their newer variants https://github.com/precice/micro-manager/pull/51
 
 ## v0.3.0
 

CITATION.cff

@@ -0,0 +1,46 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Desai
+  given-names: Ishaan
+  orcid: "https://orcid.org/0000-0002-2552-7509"
+- family-names: Scheurer
+  given-names: Erik
+  orcid: "https://orcid.org/0009-0000-9396-2994"
+- family-names: Bringedal
+  given-names: Carina
+  orcid: "https://orcid.org/0000-0003-0495-2634"
+- family-names: Uekermann
+  given-names: Benjamin
+  orcid: "https://orcid.org/0000-0002-1314-9969"
+doi: 10.18419/darus-3764
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Desai
+    given-names: Ishaan
+    orcid: "https://orcid.org/0000-0002-2552-7509"
+  - family-names: Scheurer
+    given-names: Erik
+    orcid: "https://orcid.org/0009-0000-9396-2994"
+  - family-names: Bringedal
+    given-names: Carina
+    orcid: "https://orcid.org/0000-0003-0495-2634"
+  - family-names: Uekermann
+    given-names: Benjamin
+    orcid: "https://orcid.org/0000-0002-1314-9969"
+  date-published: 2023-11-07
+  doi: 10.21105/joss.05842
+  issn: 2475-9066
+  issue: 91
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 5842
+  title: "Micro Manager: a Python package for adaptive and flexible
+    two-scale coupling"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.05842"
+  volume: 8
+title: "Micro Manager: a Python package for adaptive and flexible
+  two-scale coupling"

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing to the Micro Manager
+
+Contributions to the Micro Manager are most welcome! Please have a look at the page [contributing to preCICE](https://precice.org/community-contribute-to-precice.html) and also this page for more details.
+
+## Automatic checks
+
+We check every contribution with a few GitHub Actions workflows that report at the bottom of each pull request. For example, we have an Action to check if the contributed code is formatting correctly according to [autopep8](https://pypi.org/project/autopep8/).
+
+## Changelog
+
+We maintain a `CHANGELOG.md` where all major changes and contributions are entered.

README.md

@@ -12,10 +12,10 @@
     <img src="https://github.com/precice/micro-manager/actions/workflows/pythonpublish.yml/badge.svg" alt="Upload Python Package">
 </a>
 
+[![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/).
 
 The main documentation is rendered on the [preCICE website](https://precice.org/tooling-micro-manager-overview.html).
 
 Please report any [issues](https://github.com/precice/micro-manager/issues) and give us feedback through [one of our community channels](https://precice.org/community-channels.html).
-
-The concept and initial design of the Micro Manager is described in *Desai, Ishaan, & Bringedal, Carina & Uekermann, Benjamin. A flexible software approach to simulate two-scale coupled problems. ECCOMAS Congress 2022. [10.23967/eccomas.2022.037](https://doi.org/10.23967/eccomas.2022.037)*.

docs/micro-simulation-convert-to-library.md

@@ -14,19 +14,24 @@ Restructure your micro simulation code into a Python class with the structure gi
 
 ```python
 class MicroSimulation: # Name is fixed
-    def __init__(self):
+    def __init__(self, sim_id):
         """
         Constructor of class MicroSimulation.
+
+        Parameters
+        ----------
+        sim_id : int
+            ID of the simulation instance, that the Micro Manager has set for it.
         """
 
     def initialize(self) -> dict:
         """
-        Initialize the micro simulation. This function is *optional*.
+        Initialize the micro simulation and return initial data which will be used in computing adaptivity before the first time step.
 
         Returns
         -------
-        data : dict
-            Python dictionary with names of micro data as keys and the data as values at the initial condition
+        initial_data : dict
+            Dictionary with names of initial data as keys and the initial data itself as values.
         """
 
     def solve(self, macro_data: dict, dt: float) -> dict:

docs/running.md

@@ -18,8 +18,6 @@ from micro_manager import MicroManager
 
 manager = MicroManager("micro-manager-config.json")
 
-manager.initialize()
-
 manager.solve()
 ```
 

examples/.gitignore

@@ -1,7 +1,7 @@
 # preCICE related files
 *.log
 *events.json
-precice-run/
+precice-events/
 
 # PyCharm related files
 .idea

examples/README.md

@@ -1,18 +1,25 @@
 # Solverdummies
 
-The `solverdummies` are minimal working examples for using the preCICE Micro Manager with different languages. At the moment, there are examples for Python, and C++. They can be coupled with any other solver, for example the `macro-dummy.py` in this directory.
+The `solverdummies` are minimal working examples for using the preCICE Micro Manager with different languages. At the moment, there are examples for Python, and C++. They can be coupled with any other solver, for example the `macro_dummy.py` in this directory.
 
 ## Python
 
 To run the Python solverdummies, run the following commands in the `examples/` directory in **two different terminals**:
 
 ```bash
-python macro-dummy.py
-python python-dummy/run_micro_manager.py
+python macro_dummy.py
+python python-dummy/run_micro_manager.py --config micro-manager-config.json
 ```
 
 Note that running `micro_manager micro-manager-config.json` from the terminal will not work, as the path in the configuration file is relative to the current working directory. See [#36](https://github.com/precice/micro-manager/issues/36) for more information.
 
+To run the Python solverdummies with adaptivity run the following commands in the `examples/` directory in **two different terminals**:
+
+```bash
+python macro_dummy.py
+python python-dummy/run_micro_manager.py --config micro-manager-adaptivity-config.json
+```
+
 ## C++
 
 The C++ solverdummies have to be compiled first using [`pybind11`](https://pybind11.readthedocs.io/en/stable/index.html). To do so, install `pybind11` using `pip`:
@@ -42,12 +49,15 @@ Then, run the following commands in the `examples/` directory, in **two differen
 
 ```bash
 python macro_dummy.py
-python cpp-dummy/run_micro_manager.py
+python cpp-dummy/run_micro_manager.py --config micro-manager-config.json
 ```
 
-When changing the C++ solverdummy to your own solver, make sure to change the `PYBIND11_MODULE` in `micro_cpp_dummy.cpp` to the name that you want to compile to.
-For example, if you want to import the module as `my_solver`, change the line to `PYBIND11_MODULE(my_solver, m) {`. Then, change the `micro_file_name` in `micro-manager-config.json` to `my_solver`.
+To run the C++ solverdummies with adaptivity run the following commands in the `examples/` directory in **two different terminals**:
 
-### Adaptivity
+```bash
+python macro_dummy.py
+python cpp-dummy/run_micro_manager.py --config micro-manager-adaptivity-config.json
+```
 
-For the case of adaptivity, the deepcopy function also has to be implemented for the C++ class. An example is provided in the `cpp-dummy` directory.
+When changing the C++ solverdummy to your own solver, make sure to change the `PYBIND11_MODULE` in `micro_cpp_dummy.cpp` to the name that you want to compile to.
+For example, if you want to import the module as `my_solver`, change the line to `PYBIND11_MODULE(my_solver, m) {`. Then, change the `micro_file_name` in `micro-manager-config.json` to `my_solver`.