Post process

book/_toc.yml

@@ -32,6 +32,13 @@ parts:
     - file: content/temperatures/temperatures_basic
     - file: content/temperatures/temperatures_advanced
 
+  - caption: Post-processing
+    chapters:
+    - file: content/post_process/derived
+    - file: content/post_process/exports
+    - file: content/post_process/paraview
+    - file: content/post_process/pyvista
+
   - caption: Applications
     chapters:
     - file: content/applications/task02

book/content/post_process/derived.md

@@ -0,0 +1,111 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+kernelspec:
+  display_name: festim-workshop
+  language: python
+  name: python3
+---
+
+# Derived quantities #
+
+This tutorial goes over FESTIM's built-in functions to help users export derived results.
+
+Objectives:
+* Exporting surface quantities
+* Exporting volume quantities
+* Exporting multiple derived quantities
+
++++
+
+## Exporting surface quantities ##
+
+Users can export surface values in FESTIM by passing in the desired `field`, `SurfaceSubdomain`, and an optional `filename` (ending in `.txt` or `.csv`).
+
+To get total, average, minimum, and maximum surface values, we can use the `TotalSurface`, `AverageSurface`, `MinimumSurface`, and `MaximumSurface` classes:
+
+```{code-cell} ipython3
+import festim as F
+
+left = F.SurfaceSubdomain(1)
+H = F.Species("H")
+
+my_total = F.TotalSurface(field=H, surface=left,filename="total.csv")
+my_average = F.AverageSurface(field=H, surface=left,filename="avg.csv")
+my_minimum = F.MinimumSurface(field=H, surface=left,filename="min.csv")
+my_maximum = F.MaximumSurface(field=H, surface=left,filename="max.csv")
+```
+
+These exports will result in a text file with a list of data points and corresponding time steps. General surface quantities can be exported using `SurfaceQuantity`.
+
+We can also calculate the surface flux using the `SurfaceFlux` class:
+
+```{code-cell} ipython3
+my_flux = F.SurfaceFlux(field=H, surface=left,filename="flux.csv")
+```
+
+## Exporting volume quantities ##
+
+Volume quanities can similary be exported in FESTIM, except now we must pass in a `VolumeSubdomain`.
+
+To get total, average, minimum, and maximum volume values, we can use the `TotalVolume`, `AverageVolume`, `MinimumVolume`, and `MaximumVolume` classes:
+
+```{code-cell} ipython3
+import festim as F
+
+mat = F.Material(D_0=1, E_D=0)
+vol = F.VolumeSubdomain(1,material=mat)
+H = F.Species("H")
+
+my_total = F.TotalVolume(field=H, volume=vol,filename="total.csv")
+my_average = F.AverageVolume(field=H, volume=vol,filename="avg.csv")
+my_minimum = F.MinimumVolume(field=H, volume=vol,filename="min.csv")
+my_maximum = F.MaximumVolume(field=H, volume=vol,filename="max.csv")
+```
+
+General volume quantities can be exported using `VolumeQuantity`.
+
++++
+
+## Exporting multiple derived quanitites ##
+
+To export your results from a FESTIM simulation, you can pass a list of derived quantity objects into the `export` attribute for your problem:
+
+```{code-cell} ipython3
+import numpy as np
+import festim as F
+from dolfinx.mesh import create_unit_square
+from mpi4py import MPI
+
+mesh = create_unit_square(MPI.COMM_WORLD, 10, 10)
+my_model = F.HydrogenTransportProblem()
+my_model.mesh = F.Mesh(mesh)
+mat = F.Material(D_0=1, E_D=0)
+right_surface = F.SurfaceSubdomain(id=1, locator = lambda x: np.isclose(x[0], 1.0))
+left_surface = F.SurfaceSubdomain(id=2, locator = lambda x: np.isclose(x[0], 0.0))
+vol = F.VolumeSubdomain(id=1, material=mat)
+H = F.Species("H")
+
+max_surface = F.MaximumSurface(field=H, surface=left_surface)
+avg_vol = F.AverageVolume(field=H, volume=vol)
+
+my_model.subdomains = [right_surface, left_surface, vol]
+my_model.species = [H]
+my_model.boundary_conditions = [
+    F.FixedConcentrationBC(subdomain=left_surface, value=1, species=H)
+]
+my_model.temperature = 400
+my_model.settings = F.Settings(atol=1e10,rtol=1e-10,transient=False)
+my_model.exports = [
+    max_surface,
+    avg_vol
+]
+
+my_model.initialise()
+my_model.run()
+```

book/content/post_process/exports.md

@@ -0,0 +1,142 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+kernelspec:
+  display_name: festim-workshop
+  language: python
+  name: python3
+---
+
+# Field exports #
+
+FESTIM has classes to creae XDMF and VTX exports, which can then be viewed in Paraview (see our intro to Paraview tutorial here)!
+
+Objectives:
+* Writing XDMF files
+* Writing VTX files
+* Exporting fields in a discontinuous problem
+
++++
+
+## Writing XDMF files ##
+
+Users can export functions to XDMF files using the `XDMFExport` class, which requires a `filename` and `field`:
+
+```{code-cell} ipython3
+import festim as F
+
+H = F.Species("H")
+my_export = F.XDMFExport(filename="my_export.xdmf", field=H)
+```
+
+## Writing VTK files ##
+
+Users can also export temperature and concentration fields to VTX files using `VTXTemperatureExport` and `VTKSpeciesExport`, respectively. For both classes, we need to provide the `filename` for the output and an optional list of `times` (exports all times otherwise, defaults to `None`).
+
+To export a temperature field using `VTXTemperatureExport`:
+
+```{code-cell} ipython3
+import festim as F
+
+my_model = F.HydrogenTransportProblem()
+my_model.exports = [
+    F.VTXTemperatureExport(filename="out.bp",times=[0, 5, 10])
+]
+```
+
+Exporting the concentration also requires us to define the `field` to export, which `subdomain` to export on (defaults to all if none is provided), and the option to turn on `checkpoints` (exports to a checkpoint file using __[adios4dolfinx](https://github.com/jorgensd/adios4dolfinx)__) (defaults to `False`):
+
+```{code-cell} ipython3
+H = F.Species("H")
+subdomain = F.SurfaceSubdomain(id=1)
+my_model.species = [H]
+my_model.exports = [
+    F.VTXSpeciesExport(filename="out.bp",field=H,subdomain=subdomain,checkpoint=False)
+]
+```
+
+## Exporting fields in a discontinuous problem ##
+
+Consider the same __[multi-material problem](https://festim-workshop.readthedocs.io/en/festim2/content/material/material_basics.html#multi-material-example)__ in the Materials chapter, where we use `HydrogenTransportProblemDiscontinuous` to solve a multi-material problem:
+
+```{code-cell} ipython3
+import festim as F
+import numpy as np
+from dolfinx.mesh import create_unit_square
+from mpi4py import MPI
+
+fenics_mesh = create_unit_square(MPI.COMM_WORLD, 10, 10)
+festim_mesh = F.Mesh(fenics_mesh)
+
+my_model = F.HydrogenTransportProblemDiscontinuous()
+
+material_top = F.Material(
+    D_0=1,    
+    E_D=0,     
+    K_S_0=2,  
+    E_K_S=0,     
+)
+
+material_bottom = F.Material(
+    D_0=2,    
+    E_D=0,     
+    K_S_0=3,    
+    E_K_S=0,     
+)
+
+top_volume = F.VolumeSubdomain(id=3, material=material_top, locator=lambda x: x[1] >= 0.5)
+bottom_volume = F.VolumeSubdomain(id=4, material=material_bottom, locator=lambda x: x[1] <= 0.5)
+
+top_surface = F.SurfaceSubdomain(id=1, locator=lambda x: np.isclose(x[1], 1.0))
+bottom_surface = F.SurfaceSubdomain(id=2, locator=lambda x: np.isclose(x[1], 0.0))
+
+my_model.mesh = festim_mesh
+my_model.subdomains = [top_surface, bottom_surface, top_volume, bottom_volume]
+
+my_model.interfaces = [F.Interface(5, (bottom_volume, top_volume), penalty_term=1000)]
+my_model.surface_to_volume = {
+    top_surface: top_volume,
+    bottom_surface: bottom_volume,
+}
+
+H = F.Species("H")
+my_model.species = [H]
+H.subdomains = [top_volume, bottom_volume]
+
+my_model.temperature = 400
+
+my_model.boundary_conditions = [
+    F.FixedConcentrationBC(subdomain=top_surface, value=1.0, species=H),
+    F.FixedConcentrationBC(subdomain=bottom_surface, value=0.0, species=H),
+]
+
+my_model.settings = F.Settings(atol=1e-10, rtol=1e-10, transient=False)
+```
+
+Instead of viewing the results using PyVista, we can export the fields for each subdomain in Paraview using `VTXSpeciesExport`:
+
+```{code-cell} ipython3
+top_export = F.VTXSpeciesExport(filename="top.bp", field=H, subdomain=top_volume)
+bottom_export = F.VTXSpeciesExport(filename="bottom.bp", field=H, subdomain=bottom_volume)
+my_model.exports = [
+    top_export,
+    bottom_export,
+]
+my_model.initialise()
+my_model.run()
+```
+
+```{image} multi_material_paraview.png
+:alt: multi
+:class: bg-primary mb-1
+:align: center
+```
+
+```{note}
+For multi-material discontinuous problems, exports need to be written to VTX files, not XDMF.
+```

book/content/post_process/paraview.md

@@ -0,0 +1,13 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+---
+
+# Paraview #
+
++++