Merge pull request #1 from MindTheGap-ERC/Add_improve_and_generate_do…

…cumentation Add improve and generate documentation
MindTheGap-ERC · Oct 21, 2024 · 0c0d844 · 0c0d844
2 parents d07c9bd + 9b8372b
commit 0c0d844
Show file tree

Hide file tree

Showing 9 changed files with 6,218 additions and 6 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,50 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # install all dependencies (including pdoc)
+      - run: pip install pipenv
+      - run: pipenv install
+      - run: pipenv shell
+      # build your documentation into docs/.
+      - run: pdoc marlpde/*.py -o ./docs/
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./marlpde.html"/>
+</head>
+</html>
diff --git a/docs/marlpde.html b/docs/marlpde.html
diff --git a/docs/marlpde/Evolve_scenario.html b/docs/marlpde/Evolve_scenario.html
diff --git a/docs/marlpde/LHeureux_model.html b/docs/marlpde/LHeureux_model.html
diff --git a/docs/marlpde/parameters.html b/docs/marlpde/parameters.html
diff --git a/docs/search.js b/docs/search.js
diff --git a/marlpde/Evolve_scenario.py b/marlpde/Evolve_scenario.py
@@ -17,11 +17,54 @@
 matplotlib.use("AGG")
 
 def integrate_equations(solver_parms, tracker_parms, pde_parms):
-    '''
+    '''Perform the integration and display and store the results.
+
     This function retrieves the parameters of the Scenario to be simulated and 
     the solution parameters for the integration. It then integrates the five
     partial differential equations from L'Heureux, stores and returns the 
-    solution, to be used for plotting.
+    solution, to be used for plotting. Its inputs come from the parameters
+    module, which has dataclasses governing the solver, storage and model specs,
+    through the solver_parms, tracker_parms and pde_parms dicts, respectively.
+
+    A progress bar shows how long the (remaining) integration will take.
+
+    Parameters:
+    -----------
+    solver_parms: dict 
+        Parameters about solver settings.
+    tracker_parms: dict 
+        Parameters about the progress bar and time interval for storage
+    pde_parms: dict
+        Model parameters, which govern e.g. the physical processes, but
+        also the discretization, such as the number of grid cells.
+
+    Returns:
+    --------
+    field_solutions: ndarray
+        This is the "y" attribute of "sol" i.e. the solution derived by
+        solve_ivp. See the scipy.integrate.solve_ivp documentation for
+        some background. A reshape has been applied to arrive at one row per
+        field. The solutions as a function of time have been removed such that
+        only the solution for the last time is returned.
+
+    covered_time: float
+        This is the time interval of integration in years, from the start time
+        (probably 0) until the requested final time. When the integration halted
+        unexpectedly, the covered_time corresponds to the time covered until the
+        integration halted.
+
+    depths: pde.CartesianGrid
+        These are the centers of the grid cells that together constitute the 
+        grid.
+    
+    Xstar: float
+        Scaling factor between physical depths and dimensionless depths as used
+        in the differential equations.
+
+    Store_folder: str
+        Could be a relative path, i.e.  a path relative to the root of this 
+        repository, to a folder where solutions of the integration should be 
+        stored. Could also be an absolute path, though.
     '''
 
     Xstar = pde_parms["Xstar"]
@@ -63,7 +106,7 @@ def integrate_equations(solver_parms, tracker_parms, pde_parms):
 
     slices_all_fields = [slice(i * Number_of_depths, (i+1) * Number_of_depths) \
                              for i in range(5)]            
-    
+
     eq = LMAHeureuxPorosityDiff(depths, slices_all_fields, not_too_shallow, 
                                 not_too_deep, **filtered_pde_parms)     
 
@@ -149,9 +192,9 @@ def integrate_equations(solver_parms, tracker_parms, pde_parms):
           f"{end_computing - start_computing:.2e}s. \n"))
 
     if sol.status == 0:
-        covered_time = Tstar * end_time
+        covered_time = Tstar * (end_time - t0)
     else:
-        covered_time = pbar.n * Tstar * end_time / no_progress_updates 
+        covered_time = pbar.n * Tstar * (end_time - t0) / no_progress_updates 
 
     # Store your results somewhere in a subdirectory of a parent directory.
     store_folder = "../Results/" + \

diff --git a/pyproject.toml b/pyproject.toml
@@ -6,7 +6,7 @@ authors = ["Hanno Spreeuw <[email protected]>", "Johan Hidding <j.hidd
 license = "Apache-2"
 
 [tool.poetry.dependencies]
-python = ">=3.10,<3.12"
+python = ">=3.10,<=3.12"
 py-pde = "^0.32.0"
 tqdm = "^4.64.1"
 numpy = "^1.23.5"