Permalink
Browse files

Merge pull request #12597 from rwcarlsen/example-doc

improve example 8
  • Loading branch information...
permcody committed Dec 10, 2018
2 parents 77542f5 + 3088fe6 commit 2e50649aedf608e352586437871882f1effe7501
@@ -28,6 +28,7 @@ class ExampleConvection : public Kernel
virtual Real computeQpJacobian() override;

private:
// we will store a material property instead of VariableGradient (like example 3):
const MaterialProperty<RealGradient> & _velocity;
};

@@ -13,15 +13,11 @@
#include "Material.h"
#include "LinearInterpolation.h"

// Forward Declarations
class ExampleMaterial;

template <>
InputParameters validParams<ExampleMaterial>();

/**
* Example material class that defines a few properties.
*/
class ExampleMaterial : public Material
{
public:
@@ -31,27 +27,17 @@ class ExampleMaterial : public Material
virtual void computeQpProperties() override;

private:
/**
* This is the member reference that will hold the computed values
* for the Real value property in this class.
*/
/// member variable to hold the computed diffusivity coefficient
MaterialProperty<Real> & _diffusivity;

/**
* Computed values for the Gradient value property in this class.
*/
/// member variable to hold the computed convection velocity gradient term
MaterialProperty<RealGradient> & _convection_velocity;

/**
* This is the member reference that will hold the gradient
* of the coupled variable
*/
/// A place to store the coupled variable gradient for calculating the convection velocity
/// property.
const VariableGradient & _diffusion_gradient;

/**
* This object returns a piecewise linear function based an a series
* of points and their corresponding values
*/
/// A helper object for performaing linear interpolations on tabulated data for calculating the
/// diffusivity property.
LinearInterpolation _piecewise_func;
};

@@ -21,16 +21,15 @@ validParams<ExampleConvection>()

ExampleConvection::ExampleConvection(const InputParameters & parameters)
: Kernel(parameters),

// Retrieve a gradient material property to use for the convection
// velocity
// Retrieve and store gradient from a material property to use for the convection velocity
_velocity(getMaterialProperty<RealGradient>("convection_velocity"))
{
}

Real
ExampleConvection::computeQpResidual()
{
// Use the velocity gradient just like before in example 3
return _test[_i][_qp] * (_velocity[_qp] * _grad_u[_qp]);
}

@@ -17,12 +17,16 @@ validParams<ExampleMaterial>()
{
InputParameters params = validParams<Material>();

// Vectors for Linear Interpolation
// Allow users to specify vectors defining the points of a piecewise function formed via linear
// interpolation.
params.addRequiredParam<std::vector<Real>>(
"independent_vals", "The vector of indepedent values for building the piecewise function");
"independent_vals",
"The vector of z-coordinate values for a piecewise function's independent variable");
params.addRequiredParam<std::vector<Real>>(
"dependent_vals", "The vector of depedent values for building the piecewise function");
"dependent_vals", "The vector of diffusivity values for a piecewise function's dependent");

// Allow the user to specify which independent variable's gradient to use for calculating the
// convection velocity property:
params.addCoupledVar(
"diffusion_gradient",
"The gradient of this variable will be used to compute a velocity vector property.");
@@ -32,18 +36,19 @@ validParams<ExampleMaterial>()

ExampleMaterial::ExampleMaterial(const InputParameters & parameters)
: Material(parameters),
// Declare that this material is going to provide a Real
// valued property named "diffusivity" that Kernels can use.
// Declare that this material is going to provide a Real value typed
// material property named "diffusivity" that Kernels and other objects can use.
// This property is "bound" to the class's "_diffusivity" member.
_diffusivity(declareProperty<Real>("diffusivity")),

// Declare that this material is going to provide a RealGradient
// valued property named "convection_velocity" that Kernels can use.
// Also declare a second "convection_velocity" RealGradient value typed property.
_convection_velocity(declareProperty<RealGradient>("convection_velocity")),

// Get the reference to the variable coupled into this Material
// Get the reference to the variable coupled into this Material.
_diffusion_gradient(isCoupled("diffusion_gradient") ? coupledGradient("diffusion_gradient")
: _grad_zero),

// Initialize our piecewise function helper with the user-specified interpolation points.
_piecewise_func(getParam<std::vector<Real>>("independent_vals"),
getParam<std::vector<Real>>("dependent_vals"))
{
@@ -52,9 +57,10 @@ ExampleMaterial::ExampleMaterial(const InputParameters & parameters)
void
ExampleMaterial::computeQpProperties()
{
// We will compute the diffusivity based on the Linear Interpolation of the provided vectors in
// the z-direction
// Diffusivity will be the value of the (linearly-interpolated) piece-wise function described by
// the user.
_diffusivity[_qp] = _piecewise_func.sample(_q_point[_qp](2));

// Convection velocity is set equal to the gradient of the variable set by the user.
_convection_velocity[_qp] = _diffusion_gradient[_qp];
}
@@ -3,19 +3,34 @@
## Problem statement

This problem considers a coupled systems of equations on a 3-D domain $\Omega$ : find $u$ and $v$
such that $-\nabla \cdot \nabla u + \nabla\vec{v} \cdot \nabla u = 0$ and
such that

$-\nabla \cdot \nabla v = 0$,
\begin{equation}
\begin{aligned}
-\nabla \cdot \nabla u + \nabla\vec{v} \cdot \nabla u = 0 \\
-\nabla \cdot \nabla v = 0
\end{aligned}
\end{equation}

where $u=v=0$ on the top boundary and $u=2$ and $v=1$ on the bottom boundary. The remaining
boundaries are natural boundaries: $\nabla u \cdot \hat{n} = 0$ and $\nabla v \cdot \hat{n} = 0$.
The domain, $\Omega$, is the same as utilized in Example 2.
boundaries are natural boundaries:

The weak form of this equation, in inner-product notation, is given by:
\begin{equation}
\begin{aligned}
\nabla u \cdot \hat{n} = 0 \\
\nabla v \cdot \hat{n} = 0
\end{aligned}
\end{equation}

$(\nabla u_h, \nabla \phi_i) + (\nabla\vec{v} \cdot \nabla u, \phi_i)= 0 \quad \forall \phi_i$ and
The domain, $\Omega$, is the same as utilized in Example 2. The weak form of this equation, in
inner-product notation, is given by:

$(\nabla\vec{v}, \nabla\phi_i)= 0 \quad \forall \phi_i$,
\begin{equation}
\begin{aligned}
(\nabla u_h, \nabla \phi_i) + (\nabla\vec{v} \cdot \nabla u, \phi_i)= 0 \quad \forall \phi_i \\
(\nabla\vec{v}, \nabla\phi_i)= 0 \quad \forall \phi_i
\end{aligned}
\end{equation}

where $\phi_i$ are the test functions and $u_h$ and $v_h$ are the finite element solutions.

@@ -94,10 +109,16 @@ using Peacock or an external application that supports the Exodus II format (e.g
# 1D exact solution

A simplified 1D analog of this problem is given as follows, where $u(0)=0$ and $u(1)=1$:
$-\epsilon \frac{d^2 u}{d x^2} + \frac{d u}{d x} = 0$

The exact solution to this problem is
$u = \frac{\exp\left(\frac{x}{\epsilon}\right) - 1}{\exp\left(\frac{1}{\epsilon}\right) - 1}$
\begin{equation}
-\epsilon \frac{d^2 u}{d x^2} + \frac{d u}{d x} = 0
\end{equation}

The exact solution to this problem is:

\begin{equation}
u = \frac{\exp\left(\frac{x}{\epsilon}\right) - 1}{\exp\left(\frac{1}{\epsilon}\right) - 1}
\end{equation}

## Complete Source Files

@@ -1,24 +1,19 @@
# Example 07 : Custom Initial Conditions

[](---)

## Complete Source Files

[transient.i](https://github.com/idaholab/moose/blob/devel/examples/ex07_ics/transient.i)

[ExampleIC.h](https://github.com/idaholab/moose/blob/devel/examples/ex07_ics/include/ics/ExampleIC.h)

[ExampleIC.C](https://github.com/idaholab/moose/blob/devel/examples/ex07_ics/src/ics/ExampleIC.C)

[ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex07_ics/src/base/ExampleApp.C)

[](---)

## Outputs
# Results

!media large_media/examples/ex7-1-out.png
style=width:50%;

!media large_media/examples/ex7-2-out.png
style=width:50%;

## Complete Source Files

- [examples/ex07_ics/transient.i]
- [examples/ex07_ics/include/ics/ExampleIC.h]
- [examples/ex07_ics/src/ics/ExampleIC.C]
- [examples/ex07_ics/src/base/ExampleApp.C]

@@ -1,53 +1,126 @@
# Example 8 : Material Properties

[](---)
MOOSE includes built-in support for creating and sharing material properties thorughout your
simulation calculations. Material property calculations are run/updated by MOOSE automatically for
every quadrature point. Kernels, Postprocessors, and other objects all have convenient access to
these properties. This example demonstrates a convection-diffusion problem with kernels that
utilize custom non-linear material properties.

## Overview
## Problem Statement

- This is a convection-diffusion problem with a non-linear material property.
- The `ExampleDiffusion` kernel uses a coefficent produced from a linearly interpolated tabulated Material property.
- The `ExampleMaterial` object couples in the gradient of the "diffused" variable and uses it to make a gradient material property.
- The `ExampleConvection` kernel uses the gradient material property as a velocity vector.
This problem considers the same coupled system from [Example 3](examples/ex03_coupling.md):

[](---)
\begin{equation}
\begin{aligned}
-\nabla \cdot \nabla u + \nabla\vec{v} \cdot \nabla u = 0 \\
-\alpha \nabla \cdot \nabla v = 0
\end{aligned}
\end{equation}

## Complete Source Files
but with slightly different boundary conditions: $u=v=0$ on the bottom boundary and $u=5$ and
$\nabla v=1$ on the top boundary. The remaining boundaries taking the natural boundary condition.
$\alpha$ is a diffusivity coefficient and $\nabla\vec{v}$ is a convection coefficient derived from
the coupled $v$ diffusion equation.

## Creating Material Objects

You create custom material properties by writing your own Material class:

!listing examples/ex08_materials/include/materials/ExampleMaterial.h start=#include end=private:

The `ExampleMaterial` object couples to the gradient of the "diffused" variable and uses this to
make the "convection_velocity" material property. It also uses tabulated values specified in its
input file parameters and the z-coordinate of the current quadrature point to linearly interpolate
values for a "diffusivity" property. We need to create member variables to hold the material
properties in addition to ones for helping compute those property values:

!listing examples/ex08_materials/include/materials/ExampleMaterial.h start=private: max-height=10000

Then we need to specify appropriate input file parameters for users and write code that retrieves
the data for use in calculations:

[ex08.i](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/ex08.i)
!listing examples/ex08_materials/src/materials/ExampleMaterial.C start=#include end=ExampleMaterial::computeQpProperties max-height=10000

[ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/src/base/ExampleApp.C)
The `computeQpProperties` function is where we put the code for actually calculating the material
property values. It will be automatically called by MOOSE at the right times and for each
quadrature point. When we calculate a material property value, we "set" it by storing the
calculated value in the member variable that was bound to the corresponding property in the
class's constructor (i.e. _diffusivity and _convection_velocity):
## Example Material Object
!listing examples/ex08_materials/src/materials/ExampleMaterial.C re=void\sExampleMaterial::computeQpProperties.*$
[ExampleMaterial.h](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/include/materials/ExampleMaterial.h)
## Plumbing Into Materials
[ExampleMaterial.C](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/src/materials/ExampleMaterial.C)
In order to use the material properties we created, we need objects (e.g. our Kernels) to actually
support reading information from material properties. For this problem, the `ExampleDiffusion`
kernel will use a "diffusivity" material property coefficient provided by our `ExampleMaterial`
class/object. To do this we to have special code in three places:
[](---)
- A member variable to store the material property value:
## Diffusion with Material Property
```
const MaterialProperty<Real> & _diffusivity;
```
[ExampleDiffusion.h](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/include/kernels/ExampleDiffusion.h)
- A line in our constructor to bind our material property member to the value that is computed by
the actual Material object:
[ExampleDiffusion.C](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/src/kernels/ExampleDiffusion.C)
```
ExampleDiffusion::ExampleDiffusion(const InputParameters & parameters)
: Diffusion(parameters), _diffusivity(getMaterialProperty<Real>("diffusivity"))
{
}
```
[](---)
- Code that uses the material property to calculate something (e.g. our residual and jacobian):
## Convection with Material Property
```
Real
ExampleDiffusion::computeQpResidual()
{
return _diffusivity[_qp] * Diffusion::computeQpResidual();
...
```
[ExampleConvection.h](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/include/kernels/ExampleConvection.h)
Instead of directly coupling another variable into the convection kernel to use as the velocity
gradient term as in [Example 3](examples/ex03_coupling.md), we will instead use a
"convection_velocity" material property to provide the gradient in the `ExampleConvection` kernel.
Just like for `ExampleDiffusion` we make the three changes resulting in `ExampleConvection.C`
looking something like this:
[ExampleConvection.C](https://github.com/idaholab/moose/blob/devel/examples/ex08_materials/src/kernels/ExampleConvection.C)
!listing examples/ex08_materials/src/kernels/ExampleConvection.C start=::ExampleConvection
[](---)
## Using Material Properties
## Outputs
Material properties now give us the flexibility to change/tweak our problem details without
requiring code modifications and compiling every time. Changing how the convection velocity term
is computed requires nothing more than changing Material objects we are using. Different materials
can also be applied to different subdomains/blocks in your mesh. Let's see how we can use our
material properties in an input file:
!listing examples/ex08_materials/ex08.i block=Materials
In `ex08.i`, there are two material objects with each applied to a separate named subdomain of the
mesh via the `block = '...'` lines. These objects will provide the "diffused" and
"convection_velocity" properties that our convection and diffusion kernels now look for.
## Results
!media large_media/examples/ex08_convected.png
caption=Convection
style=width:50%;
style=width:49%;display:inline-flex;
!media large_media/examples/ex08_diffused.png
caption=Diffusion
style=width:50%;
style=width:49%;display:inline-flex;margin-left:2%
## Complete Source Files
- [examples/ex08_materials/ex08.i]
- [examples/ex08_materials/include/materials/ExampleMaterial.h]
- [examples/ex08_materials/src/materials/ExampleMaterial.C]
- [examples/ex08_materials/include/kernels/ExampleDiffusion.h]
- [examples/ex08_materials/src/kernels/ExampleDiffusion.C]
- [examples/ex08_materials/include/kernels/ExampleConvection.h]
- [examples/ex08_materials/src/kernels/ExampleConvection.C]

0 comments on commit 2e50649

Please sign in to comment.