Merge pull request #12608 from rwcarlsen/example-doc

improve example 7.

examples/ex01_inputfile/ex01.i

@@ -1,4 +1,6 @@
 [Mesh]
+  # We use a pre-generated mesh file (in exodus format).
+  # This mesh file has 'top' and 'bottom' named boundaries defined inside it.
   file = mug.e
 []
 
@@ -17,24 +19,25 @@
 []
 
 [BCs]
-  [./bottom]
+  [./bottom] # arbitrary user-chosen name
     type = DirichletBC
     variable = diffused
-    boundary = 'bottom'
+    boundary = 'bottom' # This must match a named boundary in the mesh file
     value = 1
   [../]
 
-  [./top]
+  [./top] # arbitrary user-chosen name
     type = DirichletBC
     variable = diffused
-    boundary = 'top'
+    boundary = 'top' # This must match a named boundary in the mesh file
     value = 0
   [../]
 []
 
 [Executioner]
   type = Steady
   solve_type = 'PJFNK'
+  file_base = 'out'
 []
 
 [Outputs]

examples/ex05_amr/ex05.i

@@ -5,7 +5,7 @@
 # This is where mesh adaptivity magic happens:
 [Adaptivity]
   marker = errorfrac # this specifies which marker from 'Markers' subsection to use
-  steps = 6 # run adaptivity 6 times, recomputing solution, indicators, and markers each time
+  steps = 2 # run adaptivity 2 times, recomputing solution, indicators, and markers each time
 
   # Use an indicator to compute an error-estimate for each element:
   [./Indicators]

examples/ex07_ics/src/ics/ExampleIC.C

@@ -25,14 +25,11 @@ ExampleIC::ExampleIC(const InputParameters & parameters)
 {
 }
 
+// This is the primary function custom ICs must implement.
 Real
 ExampleIC::value(const Point & p)
 {
-  /**
-   * _value * x
-   * The Point class is defined in libMesh.  The spatial
-   * coordinates x,y,z can be accessed individually using
-   * the parenthesis operator and a numeric index from 0..2
-   */
+  // The Point class is defined in libMesh.  The spatial coordinates x,y,z can be accessed
+  // individually using the parenthesis operator and a numeric index from 0..2
   return 2. * _coefficient * std::abs(p(0));
 }

examples/ex07_ics/steady.i

@@ -35,7 +35,7 @@
     type = DirichletBC
     variable = diffused
     boundary = 'bottom'
-    value = 10
+    value = 8
   [../]
 []
 

examples/ex07_ics/transient.i

@@ -40,7 +40,7 @@
     type = DirichletBC
     variable = diffused
     boundary = 'bottom'
-    value = 10
+    value = 8
   [../]
 []
 

examples/ex08_materials/ex08.i

@@ -12,13 +12,13 @@
   [./diffused]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 0.5
+    initial_condition = 0.5 # shortcut/convenience for setting constant initial condition
   [../]
 
   [./convected]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 0.0
+    initial_condition = 0.0 # shortcut/convenience for setting constant initial condition
   [../]
 []
 

modules/doc/content/examples/ex01_inputfile.md

@@ -48,14 +48,7 @@ file itself:
 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]
-  [./diffused]
-    order = FIRST
-    family = LAGRANGE
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Variables
 
 ### Kernels
 
@@ -65,37 +58,15 @@ the `Diffusion` Kernel is already defined in MOOSE.  To use a particular Kernel
 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]
-  [./diff]
-    type = Diffusion
-    variable = diffused
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Kernels
 
 ### Boundary Conditions (BCs)
 
 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]
-  [./bottom]
-    type = DirichletBC
-    variable = diffused
-    boundary = 'bottom'
-    value = 1
-  [../]
-  [./top]
-    type = DirichletBC
-    variable = diffused
-    boundary = 'top'
-    value = 0
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=BCs
 
 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
@@ -114,26 +85,15 @@ The type of problem to solve and the method for solving it is defined within the
 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]
-  type = Steady
-  solve_type = 'PJFNK'
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Executioner
 
 ### 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).
 
-```text
-[Outputs]
-  file_base = out
-  screen = true
-  exodus = true
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Outputs
 
 ## Running the Problem
 
@@ -155,15 +115,6 @@ Peacock or an external application that supports the Exodus II format (e.g., Par
        caption= Example 1 Results
        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)
-
 ## Next Steps
 
 Although the Diffusion kernel is the only "physics" in the MOOSE framework, a large set of physics
@@ -174,3 +125,14 @@ implement your own physics, you will need to understand the following:
   the "weak" form of for PDEs
 - [C++](help/c++/index.md) and object-oriented design
 - [The Anatomy of a MOOSE Object](http://mooseframework.org/wiki/MooseTraining/MooseObject/)
+- Check out more [examples](examples/index.md)
+
+## 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)
+

modules/doc/content/examples/ex05_amr.md

@@ -14,7 +14,9 @@ error estimates in addition to a few [Markers](Markers/index.md).
 
 ## Results
 
-Mesh results from each refinement step in `ex05.i` are shown below:
+The results shown here are created using 6 refinement steps.  However, because it can take a while
+to run, the `ex05.i` input file only specifies running 2 mesh refinement steps.  Mesh results from
+each of the 6 refinement steps are shown below:
 
 !media large_media/examples/ex5-mesh-0.png
        style=width:50%;margin-left:0%;

modules/doc/content/examples/ex07_ics.md

@@ -1,19 +1,69 @@
 # Example 07 : Custom Initial Conditions
 
+MOOSE provides several ways to specify initial conditions (ICs) for transient problems.  The same
+functionality can be used to specify initial guesses for steady-state problems.  Custom methods
+can be created in addition to using any of many built-in methods for specifying initial
+conditions.  Detailed information for all the built-in initial conditions available can be found
+on the [Initial Condition System Documentation](syntax/ICs/index.md)
 
+This example demonstrates creating and using a custom class+object for setting the following
+initial condition:
+
+\begin{equation}
+\begin{aligned}
+    u(t=t_0, x, y, z) = 2 C x
+\end{aligned}
+\end{equation}
+
+where $C$ is a user-chosen coefficient. To accomplish this, we will need to create our own
+subclass of MOOSE's `InitialCondition` class and then specify the IC in our input file.
+
+## Creating a Custom IC
+
+We create a header file and subclass the `InitialCondition` class and add a `Real` (i.e. floating
+point number) member variable to hold the user-specified coefficient - see
+[examples/ex07_ics/include/ics/ExampleIC.h] for details. The `.C` file defines an input parameter
+named `coefficient`, stores its value in a member variable in the constructor, and uses that value
+to compute the IC.
+
+!listing examples/ex07_ics/src/ics/ExampleIC.C max-height=10000
+
+## Using ICs in an Input File
+
+The input file [examples/ex07_ics/transient.i] sets up a simple transient diffusion problem with
+initial conditions specified in the `Variables` block:
+
+!listing examples/ex07_ics/transient.i block=Variables
+
+We can also use the initial condition when running steady-state problems (i.e. with the `Steady`
+Executioner); this effectively functions as an initial guess for the solver - usually not
+necesary, but occasionally useful.  For steady cases, the IC is specified in exactly the same way
+- see e.g. [examples/ex07_ics/steady.i].
 
 # Results
 
-!media large_media/examples/ex7-1-out.png
-       style=width:50%;
+These results are from running the `transient.i` file. At $t=0$, we can see that the initial
+condition defines the solution to be zero at $x=0$ (along the rear surface of the half-cylinder)
+and increasing linearly toward us (out of the page).  At the final time, we see that diffusion has
+overcome our IC and our Dirichlet BCs have dictated the solution along the top and bottom
+surfaces.
+
+!media large_media/examples/ex07/transient_t0.png
+       style=width:33%;display:inline-flex;
+       caption=Initial state (t = 0)
 
-!media large_media/examples/ex7-2-out.png
-       style=width:50%;
+!media large_media/examples/ex07/transient_tmid.png
+       style=width:33%;display:inline-flex;
+       caption=Intermediate diffused state (t = .1)
+
+!media large_media/examples/ex07/transient_tend.png
+       style=width:33%;display:inline-flex;
+       caption=Final equilibrium state (t = 1 )
 
 ## 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]
+- [examples/ex07_ics/transient.i]
+- [examples/ex07_ics/steady.i]
 

modules/doc/content/examples/ex09_stateful_materials.md

@@ -1,25 +1,6 @@
 # Example 09 : Stateful Materials Properties
 
-[](---)
-
-## Complete Source Files
-
-[ex09.i](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/ex09.i)
-
-
-[](---)
-
-## Stateful Example Material
-
-[ExampleMaterial.h](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/include/materials/ExampleMaterial.h)
-
-[ExampleMaterial.C](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/src/materials/ExampleMaterial.C)
-
-[ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/src/base/ExampleApp.C)
-
-[](---)
-
-## Outputs
+## Results
 
 !media large_media/examples/ex9-out1.png
        caption=Beginning
@@ -29,3 +10,8 @@
        caption=End 
        style=width:50%;
 
+## Complete Source Files
+
+- [examples/ex09_stateful_materials/ex09.i]
+- [examples/ex09_stateful_materials/include/materials/ExampleMaterial.h]
+- [examples/ex09_stateful_materials/src/materials/ExampleMaterial.C]

modules/doc/content/getting_started/index.md

@@ -24,14 +24,18 @@ then you should create an application.
 
 Your application is where code and input files should be created for your particular problem.
 
-To create an application, run the stork.sh script while sitting outside the MOOSE repository with a single argument providing the name you wish to use to name your application:
+To create an application, run the stork.sh script while sitting outside the MOOSE repository with
+a single argument providing the name you wish to use to name your application:
 
 ```bash
 cd ~/projects
 ./moose/scripts/stork.sh YourAppName
 ```
 
-Running this script will create a folder named "YourAppName" in the projects directory, this application will automatically link against MOOSE. Obviously, the "YourAppName" should be the name you want to give to your application; consider the use of an acronym. We prefer animal names for applications, but you are free to choose whatever name suits your needs.
+Running this script will create a folder named "YourAppName" in the projects directory, this
+application will automatically link against MOOSE. Obviously, the "YourAppName" should be the name
+you want to give to your application; consider the use of an acronym. We prefer animal names for
+applications, but you are free to choose whatever name suits your needs.
 
 !alert note
 You should not attempt to run this script while sitting inside the MOOSE repository. Doing so will result in an error.
@@ -44,7 +48,8 @@ make -j4
 ./run_tests -j4
 ```
 
-If your application is working correctly, you should see one passing test. This indicates that  your application is ready to be further developed.
+If your application is working correctly, you should see one passing test. This indicates that
+your application is ready to be further developed.
 
 !include getting_started/installation/post_moose_install.md
 

modules/doc/content/getting_started/installation/post_moose_install.md

@@ -1,6 +1,8 @@
 ## Learn More
 
-Now that you have a working MOOSE Framework stack, there are several [examples](examples/index.md) you can peruse to familiarize yourself with the components of the input file. The input file is what you will use to build problems for your Application (and MOOSE) to solve.
+Now that you have a working MOOSE Framework stack,
+[consider checking out the examples](examples/index.md) for a beginning tour of how to use input
+files and implement your own custom behavior for MOOSE.
 
 ## Join the Community
 

modules/doc/content/index.md

@@ -29,8 +29,8 @@ domains.
 !col! class=s12 m4 l4 icon=settings
 ### Getting Started class=center style=font-weight:200;
 
-MOOSE works on Mac OS, Linux, and Windows and is easy to get started with. To begin exploring
-read our [getting_started/index.md] page.
+MOOSE works on Mac OS, Linux, and Windows and is easy to get started with. Begin by exploring
+[our getting started page](getting_started/index.md).
 
 !col-end!
 !row-end!