Merge pull request #38 from aurora-multiphysics/hsaunders1904/26_update_readme_documentation

Update documentation

Author: hsaunders1904

.github/workflows/ci.yml

@@ -23,6 +23,7 @@ jobs:
         git config --global --add safe.directory "$GITHUB_WORKSPACE"
         pre-commit install
         SKIP=no-commit-to-branch pre-commit run --all
+
     - name: Build
       shell: bash
       run: |
@@ -36,9 +37,36 @@ jobs:
 
         # Build hippo
         make -j
+
     - name: Test
       shell: bash
       run: |
         . /opt/openfoam/OpenFOAM-12/etc/bashrc || true
         pip install -r requirements.test.txt
         ./run_tests
+
+    - name: Docs
+      shell: bash
+      run: |
+        . /opt/openfoam/OpenFOAM-12/etc/bashrc || true
+        cd doc
+        ./moosedocs.py build --destination=htmldoc
+        [ -f htmldoc/index.html ]
+
+    - name: Artifact docs
+      id: deployment
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: doc/htmldoc
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && github.ref == 'main' }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build-test
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

README.md

@@ -1,6 +1,10 @@
 # hippo
 
-Moose app that wraps OpenFOAM buoyantFoam solver.
+Hippo is a MOOSE app wrapping OpenFOAM's fluid solver.
+It provides tools for solving coupled conjugate heat transfer problems.
+
+Some simple 1 and 2D validation cases can be found in
+[the tests](https://github.com/aurora-multiphysics/hippo/tree/main/test/tests/multiapps).
 
 ## Install/Build
 
@@ -78,7 +82,9 @@ METHOD=dbg make
 
 ## Tests
 
-Some basic tests can be run with `./run_tests`.
+Hippo's tests are written using MOOSE's
+[test harness system](https://mooseframework.inl.gov/python/TestHarness.html).
+Just run `./run_tests`.
 
 Note that you must have the required Python packages installed:
 
@@ -112,15 +118,43 @@ git commit --no-verify
 ## Notes
 
 This is a work in progress.
-So far hippo can:
+So far, Hippo can:
+
+- Create a 2D MOOSE boundary mesh from the boundary of an OpenFOAM mesh.
+- Run a fluid solver case via a MOOSE input file.
+- Transfer temperatures and or heat fluxes from an OpenFOAM mesh to
+  the MOOSE boundary mesh.
+- Set OpenFOAM temperature field boundary conditions
+  using values from a MOOSE mesh.
+
+### Floating Point Error Trapping
+
+If you have floating point error (FPE) trapping enabled in OpenFOAM,
+you may run into errors when running Hippo.
+
+Hippo input files that run a MOOSE case do not require a Kernel or variables.
+However, MOOSE will still happily go off and calculate a residual.
+Since there are no variables defined,
+the residual calculation results in a division by vero and an FPE signal.
+OpenFOAM will catch this signal and abort the application.
+
+There are two workarounds for this problem:
+
+1. Disable trapping for floating point exceptions.
+   `unset FOAM_SIGFPE && unset FOAM_SETNAN`.
 
-- Create a moose mesh from the boundary of an openfoam mesh
-- Can run an buoyantFOAM case via moose
-- Transfer temperature from faces of openfoam mesh to nodes of Moose mesh
+2. Add a dummy variable to the MOOSE input file.
+   E.g.,
 
-> *Note: When running in parallel add `--keep-cout` to the command line
-> because OpenFOAM will crash if a process fails to write to stdout*
+   ```toml
+   [Variables]
+     [dummy]
+       initial_value = 999
+     []
+   []
+   ```
 
 "Fork hippo" to create a new MOOSE-based application.
 
-For more information see: [http://mooseframework.org/create-an-app/](http://mooseframework.org/create-an-app/)
+For more information see:
+[http://mooseframework.org/create-an-app/](http://mooseframework.org/create-an-app/)

doc/content/developer_guide.md

@@ -2,6 +2,15 @@
 
 This page contains information to aid in development of Hippo.
 
+## Documentation
+
+The project uses the MOOSE docs system to generate its HTML documentation.
+The HTML artifacts are generated and deployed within Hippo's CI.
+The CI pipeline is run on any pull request
+and also on a push to `main` (i.e., a merged pull request).
+The documentation pages are always built,
+however they are only deployed on a push to `main`.
+
 ## Docker
 
 The Dockerfile `docker/Dockerfile` contains the build definition for

doc/content/hit/step_by_step/flow_over_heated_plate.i

@@ -0,0 +1,158 @@
+[Mesh]
+    [solid]
+        type = GeneratedMeshGenerator
+        boundary_name_prefix = solid
+        dim = 3
+
+        nx = 161
+        xmin = 0
+        xmax = 1
+
+        ny = 16
+        ymin = -0.25
+        ymax = 0
+
+        nz = 1
+        zmin = 0
+        zmax = 0.4
+
+        # Calculated here:
+        # https://openfoamwiki.net/index.php/Scripts/blockMesh_grading_calculation
+        # Based on a grading factor of 5 and 161 elements.
+        bias_x = 1.010109749
+    []
+[]
+
+[Variables]
+    [temp]
+        family = LAGRANGE
+        order = FIRST
+        initial_condition = 310
+    []
+[]
+
+[Kernels]
+    [heat-conduction]
+        type = HeatConduction
+        variable = temp
+    []
+    [heat-conduction-dt]
+        type = HeatConductionTimeDerivative
+        variable = temp
+    []
+[]
+
+[BCs]
+    [fixed_temp]
+        type = DirichletBC
+        variable = temp
+        boundary = solid_bottom
+        value = 310
+    []
+
+    # Use the fluid wall temperature as a matched value boundary condition.
+    [fluid_interface]
+        type = MatchedValueBC
+        variable = temp
+        boundary = solid_top
+        v = fluid_wall_temperature
+    []
+[]
+
+[Materials]
+    # The example specifies that the thermal diffusivity of the solid should
+    # be α = 1 m2/s, and the thermal conductivity should be k = 100 W/(m.K).
+    #
+    # We know α = k/(ρ.Cp), where k is thermal conductivity, Cp is specific
+    # heat capacity, and ρ is density.
+    #
+    # Hence we require that ρ.Cp = k = 100.
+    [thermal-conduction]
+        type = HeatConductionMaterial
+        thermal_conductivity = 100.0  # W/(m.K)
+        specific_heat = 0.5  # J/(kg.K)
+    []
+    [thermal-density]
+        type = GenericConstantMaterial
+        prop_names  = 'density'
+        prop_values = 200.0  # kg/m3
+    []
+[]
+
+[AuxVariables]
+    [wall_heat_flux]
+        family = MONOMIAL
+        order = CONSTANT
+        initial_condition = 0
+    []
+
+    # Add an AuxVariable to store the wall temperature of the fluid domain.
+    [fluid_wall_temperature]
+        family = LAGRANGE
+        order = FIRST
+        initial_condition = 0
+    []
+[]
+
+[AuxKernels]
+    [heat_flux_aux]
+        type = HeatFluxAux
+        variable = wall_heat_flux
+        thermal_conductivity = 100  # W/(m.K)
+        T = temp
+        boundary = 'solid_top'
+    []
+[]
+
+[MultiApps]
+    [hippo]
+        type = TransientMultiApp
+        app_type = hippoApp
+        execute_on = timestep_begin
+        input_files = 'fluid.i'
+    []
+[]
+
+[Transfers]
+    # Copy the wall temperature from the fluid into an AuxVariable.
+    [wall_temperature_from_fluid]
+        type = MultiAppGeometricInterpolationTransfer
+        source_variable = fluid_wall_temp
+        from_multi_app = hippo
+        variable = fluid_wall_temperature
+        execute_on = same_as_multiapp
+    []
+
+    # Copy the heat flux from the 'wall_heat_flux' aux variable into the
+    # multiapp.
+    # Remember we marked the 'solid_heat_flux' variable in 'fluid.i' to be
+    # used as a heat flux boundary condition on the OpenFOAM solve.
+    [heat_flux_to_fluid]
+        type = MultiAppGeometricInterpolationTransfer
+        source_variable = wall_heat_flux
+        to_multi_app = hippo
+        variable = solid_heat_flux
+        execute_on = same_as_multiapp
+    []
+[]
+
+[Executioner]
+    type = Transient
+    start_time = 0
+    end_time = 10
+    dt = 0.025
+
+    fixed_point_abs_tol = 1e-7
+    fixed_point_rel_tol = 1e-8
+
+    solve_type = 'PJFNK'
+    petsc_options = '-snes_ksp_ew'
+    petsc_options_iname = '-pc_type -pc_hypre_type'
+    petsc_options_value = 'hypre boomeramg'
+    nl_abs_tol = 1e-7
+    nl_rel_tol = 1e-8
+[]
+
+[Outputs]
+    exodus = true
+[]

doc/content/hit/step_by_step/fluid.i

@@ -0,0 +1,37 @@
+[Mesh]
+    type = FoamMesh
+    case = 'fluid-openfoam'  # the directory of the OpenFOAM case
+    foam_patch = 'interface' # the name of the coupled boundary
+[]
+
+[AuxVariables]
+    [fluid_wall_temp]
+        family = MONOMIAL
+        order = CONSTANT
+        initial_condition = 300
+    []
+    [solid_heat_flux]
+        family = MONOMIAL
+        order = CONSTANT
+        initial_condition = 0
+    []
+[]
+
+[Problem]
+    type = FoamProblem
+    # Take the heat flux from MOOSE and set it on the OpenFOAM mesh.
+    heat_flux = solid_heat_flux
+    # Take the boundary temperature from OpenFOAM and set it on the MOOSE mesh.
+    foam_temp = fluid_wall_temp
+[]
+
+[Executioner]
+    type = Transient
+    start_time = 0
+    end_time = 10
+    dt = 0.025
+
+    [TimeStepper]
+        type = FoamTimeStepper
+    []
+[]

doc/content/images/step_by_step/flow_over_heated_plate.png

@@ -8,6 +8,10 @@ A MOOSE multiapp wrapping OpenFOAM for conjugate heat transfer problems.
 
 Build instructions can be found in the repository's README.
 
+## Setting Up a Case
+
+See a step-by-step example in [this guide](step_by_step.md).
+
 ## Developer Guide
 
 See [here](developer_guide.md) for developer documentation.