Permalink
Browse files

Merge pull request #12497 from rwcarlsen/example-docs

Add examples explanation and improve ex1
  • Loading branch information...
permcody committed Nov 16, 2018
2 parents 8c17339 + b1034fc commit 7a854a672218e46a539507a933a230566035ba35
Showing with 90 additions and 86 deletions.
  1. +60 −46 framework/doc/content/examples/ex01_inputfile.md
  2. +30 −40 framework/doc/content/examples/index.md
@@ -2,13 +2,16 @@
## Problem Statement
This example briefly describes the creation of a basic input file and the six required components for utilizing MOOSE for solving a problem.
This example briefly describes the creation of a basic input file and the six required sections
for utilizing MOOSE for solving a problem.
We consider the steady-state diffusion equation on the 3D domain $$\Omega$$: find $u$ such that $-\nabla \cdot \nabla u = 0 \in \Omega$,
$u = 1$ on the bottom, $u = 0$ on the top and with $\nabla u \cdot \hat{n} = 0$ on the remaining boundaries.
We consider the steady-state diffusion equation on the 3D domain $$\Omega$$: find $u$ such that
$-\nabla \cdot \nabla u = 0 \in \Omega$, $u = 1$ on the bottom, $u = 0$ on the top and with
$\nabla u \cdot \hat{n} = 0$ on the remaining boundaries.
The weak form ([see Finite Elements Principles](finite_element_concepts/fem_principles.md)) of this equation, in inner-product notation, is given by: $\nabla \phi_i, \nabla u_h = 0 \quad \forall \phi_i$,
where $\phi_i$ are the test functions and $u_h$ is the finite element solution.
The weak form ([see Finite Elements Principles](finite_element_concepts/fem_principles.md)) of
this equation, in inner-product notation, is given by: $\nabla \phi_i, \nabla u_h = 0 \quad
\forall \phi_i$, where $\phi_i$ are the test functions and $u_h$ is the finite element solution.
## Input File Syntax
@@ -23,8 +26,9 @@ A basic moose input file requires six parts:
### Mesh
- The domain for the problem is created with the "Mesh" block in the input file.
- Here the mesh, the mesh is read from the file mug.e.
The domain for the problem is created with the `Mesh` block in the input file. Here the mesh is
read from the file `mug.e` which is a relative path starting in the same directory as the input
file itself:
```text
@@ -33,14 +37,16 @@ A basic moose input file requires six parts:
[]
```
<br>
!media large_media/examples/mug_mesh.png
caption=mug.e mesh file
style=width:50%;
style=width:40%;display:block;margin-left:auto;margin-right:auto;
### Variables
- In this simple problem, a single variable, 'diffused,' is defined, which represents $$u$$ from the continuous problem.
- The 'diffused' variable is approximated with linear Lagrange shape functions.
In this simple problem, a single variable, 'diffused,' is defined, which represents $$u$$ from the
continuous problem. The 'diffused' variable is approximated with linear Lagrange shape functions.
```text
[Variables]
@@ -53,10 +59,11 @@ A basic moose input file requires six parts:
### Kernels
- The weak form of problem statement is represented by a `Diffusion`` Kernel` object.
- In general, users write their own Kernels and store them in their own MOOSE-based application, but in this case the Diffusion Kernel is already defined in MOOSE.
- Within the input file, to invoke the use of this object a sub-block is defined, named "diff", that utilizes the `Diffusion` `Kernel` on the previously defined variable "diffused".
The weak form of the problem statement is represented by a `Diffusion` Kernel object. In general,
users write custom Kernels that reside in their own MOOSE-based application(s), but in this case
the `Diffusion` Kernel is already defined in MOOSE. To use a particular Kernel object an input
file sub-section is defined, labeled "diff" (this is an arbitrary user-defined name), that
utilizes the `Diffusion` `Kernel` and acts on the previously defined variable "diffused".
```text
[Kernels]
@@ -69,9 +76,9 @@ A basic moose input file requires six parts:
### Boundary Conditions (BCs)
- Boundary conditions are defined in a similar manner as `Kernels`.
- For the current problem two Dirichlet boundary conditions are required, again an object for this type of boundary is already defined in a C++ object within MOOSE: `DirichletBC`.
- In the input file the two boundary conditions are applied utilizing a single C++ object as follows.
Boundary conditions are defined in a manner similar to `Kernels`. For this problem two Dirichlet
boundary conditions are required. In the input file the two boundary conditions are specified
each using the `DirichletBC` object provided by MOOSE.
```text
[BCs]
@@ -90,15 +97,22 @@ A basic moose input file requires six parts:
[]
```
- Within each of the two sub-blocks, named "top" and "bottom" by the user, the boundary conditions are linked to the associated variable ("variable = diffused") and boundary.
- The supplied mesh file, mug.e, prescribes and labels the boundaries "top" and "bottom", these are often numbers depending on how your mesh file was generated.
Within each of the two sub-section, named "top" and "bottom" by the user, the boundary conditions
are linked to their associated variable(s) (i.e. "diffused" in this case) and boundaries. In this
case, the mesh file `mug.e` defines labeled the boundaries "top" and "bottom" which we can refer
to. Boundaries will also often be specified by number IDs - depending on how your mesh file was
generated.
- Note, the Neumann boundary condition for this problem is automatically satisfied, thus there is no need to define it. However, non-zero Neumann conditions as well as many others may be defined using existing MOOSE objects (e.g., `NeumannBC`) or using custom boundary conditions derived from the existing objects within MOOSE.
Note, the Neumann boundary conditions for this problem (on the left and right sides) are satisfied
implicitly and are not necessary for us to define. However, for non-zero Neumann or other boundary
conditions many built-in objects are provided by MOOSE (e.g., `NeumannBC`). You can also create
custom boundary conditions derived from the existing objects within MOOSE.
### Executioner
- The type of problem to solve and the method for solving is defined within the `Executioner` block.
- For this problem the type is `Steady` and the method for solving is the default, Preconditioned Jacobain Free Newton Krylov.
The type of problem to solve and the method for solving it is defined within the `Executioner`
block. This problem is steady-state and will use the `Steady` Executioner and will use the
default solving method Preconditioned Jacobain Free Newton Krylov.
```text
[Executioner]
@@ -109,8 +123,9 @@ A basic moose input file requires six parts:
### Outputs
- Here two types of outputs are enabled: output to the screen (console) and output to an Exodus II file (exodus).
- Setting the "file_base" parameter is optional, in this example it forces the output file to be named "out.e" ("e" is the extension used for the Exodus II format).
Here two types of outputs are enabled: output to the screen (console) and output to an Exodus II
file (exodus). Setting the "file_base" parameter is optional, in this example it forces the
output file to be named "out.e" ("e" is the extension used for the Exodus II format).
```text
[Outputs]
@@ -122,44 +137,43 @@ A basic moose input file requires six parts:
## Running the Problem
- This example may be run using Peacock or by running the following commands form the command line.
This example may be run using Peacock or by running the following commands form the command line.
```bash
cd ~/projects/moose/examples/ex01_inputfile
make -j8
./ex01-opt -i ex01.i
```
- This will generate the results file, out.e, as shown in Figure 2. This file may be viewed using Peacock or an external application that supports the Exodus II format (e.g., Paraview).
This will generate the results file, out.e, as shown in Figure 2. This file may be viewed using
Peacock or an external application that supports the Exodus II format (e.g., Paraview).
<br>
!media large_media/examples/ex01_results.png
caption= Example 1 Results
style=width:50%;
style=width:50%;display:block;margin-left:auto;margin-right:auto;
## Complete Source Files
[ex01.i](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/ex01.i)
[main.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/main.C)
[ExampleApp.h](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/include/base/ExampleApp.h)
[ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/base/ExampleApp.C)
[Diffusion.h](https://github.com/idaholab/moose/blob/devel/framework/include/kernels/Diffusion.h)
[Diffusion.C](https://github.com/idaholab/moose/blob/devel/framework/src/kernels/Diffusion.C)
- [ex01.i](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/ex01.i)
- [main.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/main.C)
- [ExampleApp.h](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/include/base/ExampleApp.h)
- [ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/base/ExampleApp.C)
- [Diffusion.h](https://github.com/idaholab/moose/blob/devel/framework/include/kernels/Diffusion.h)
- [Diffusion.C](https://github.com/idaholab/moose/blob/devel/framework/src/kernels/Diffusion.C)
[](---)
## Next Steps
- Diffusion kernel is the only "physics" in the MOOSE framework
* A large set of physics is included in the MOOSE [modules](http://mooseframework.org/wiki/PhysicsModules/)
- In order to implement your own physics, you must understand three things:
* [Finite Element Methods](http://mooseframework.org/wiki/MooseTraining/FEM/) and the generation of a "weak" form
* [C++](http://mooseframework.org/wiki/MooseTraining/CPP/) and object-oriented design
* [The Anatomy of a MOOSE Object](http://mooseframework.org/wiki/MooseTraining/MooseObject/)
Although the Diffusion kernel is the only "physics" in the MOOSE framework, a large set of physics
is included in the MOOSE [modules](http://mooseframework.org/wiki/PhysicsModules/). In order to
implement your own physics, you will need to understand the following:
- [Finite Element Methods](http://mooseframework.org/wiki/MooseTraining/FEM/) and the generating
the "weak" form of for PDEs
- [C++](utilities/c++/index.md) and object-oriented design
- [The Anatomy of a MOOSE Object](http://mooseframework.org/wiki/MooseTraining/MooseObject/)
@@ -1,41 +1,31 @@
[Example 1 : As Simple As It Gets](examples/ex01_inputfile.md)
[Example 2 : Adding a Custom Kernel](examples/ex02_kernel.md)
[Example 3 : Multiphysics Coupling](examples/ex03_coupling.md)
[Example 4 : Custom Boundary Conditions](examples/ex04_bcs.md)
[Example 5 : Automatic Mesh Adaptivity](examples/ex05_amr.md)
[Example 6 : Transient Analysis](examples/ex06_transient.md)
[Example 7 : Custom Initial Conditions](examples/ex07_ics.md)
[Example 8 : Material Properties](examples/ex08_materials.md)
[Example 9 : Stateful Materials Properties](examples/ex09_stateful_materials.md)
[Example 10 : Auxiliary Variables](examples/ex10_aux.md)
[Example 11 : Preconditioning](examples/ex11_prec.md)
[Example 12 : Physics Based Preconditioning](examples/ex12_pbp.md)
[Example 13 : Custom Functions](examples/ex13_functions.md)
[Example 14 : Postprocessors and Code Verification](examples/ex14_pps.md)
[Example 15 : Custom Actions](examples/ex15_actions.md)
[Example 16 : Creating a Custom Timestepper](examples/ex16_timestepper.md)
[Example 17 : Adding a Dirac Kernel](examples/ex17_dirac.md)
[Example 18 : ODE Coupling](examples/ex18_scalar_kernel.md)
[Example 19 : Newton Damping](examples/ex19_dampers.md)
[Example 20 : UserObjects](examples/ex20_user_objects.md)
[Example 21 : Debugging](examples/ex21_debugging.md)
# MOOSE Usage Examples
The MOOSE repository has an `examples` directory with several subdirectories. Each subdirectory
has code for a full MOOSE-based application and input file(s) for running simulations. Each example can
be built by running binary that can be built by running `make` in the desired example's directory.
This will produce a MOOSE application binary (named e.g. `ex01-opt`) that can be used to run input
files (such as the ones in the example's own directory). A guide explaining what each example
demonstrates and how to use it is provided here:
- [Example 1: As Simple As It Gets](examples/ex01_inputfile.md)
- [Example 2: Adding a Custom Kernel](examples/ex02_kernel.md)
- [Example 3: Multiphysics Coupling](examples/ex03_coupling.md)
- [Example 4: Custom Boundary Conditions](examples/ex04_bcs.md)
- [Example 5: Automatic Mesh Adaptivity](examples/ex05_amr.md)
- [Example 6: Transient Analysis](examples/ex06_transient.md)
- [Example 7: Custom Initial Conditions](examples/ex07_ics.md)
- [Example 8: Material Properties](examples/ex08_materials.md)
- [Example 9: Stateful Materials Properties](examples/ex09_stateful_materials.md)
- [Example 10: Auxiliary Variables](examples/ex10_aux.md)
- [Example 11: Preconditioning](examples/ex11_prec.md)
- [Example 12: Physics Based Preconditioning](examples/ex12_pbp.md)
- [Example 13: Custom Functions](examples/ex13_functions.md)
- [Example 14: Postprocessors and Code Verification](examples/ex14_pps.md)
- [Example 15: Custom Actions](examples/ex15_actions.md)
- [Example 16: Creating a Custom Timestepper](examples/ex16_timestepper.md)
- [Example 17: Adding a Dirac Kernel](examples/ex17_dirac.md)
- [Example 18: ODE Coupling](examples/ex18_scalar_kernel.md)
- [Example 19: Newton Damping](examples/ex19_dampers.md)
- [Example 20: UserObjects](examples/ex20_user_objects.md)
- [Example 21: Debugging](examples/ex21_debugging.md)

0 comments on commit 7a854a6

Please sign in to comment.