In the following four tutorials, you will edit a template file (found in your Gale installation directory at input/cookbook/template.xml) to create customized input files. You should be able to use the template file as a basis for most of your own input files.

More tutorials are found in Chapter 5 of the Gale User Manual

About Modifying the Template File

Adding Lines to the Template File

Unless otherwise specified, when you are instructed to add sections to the input file, that text should be added after the line:

       <struct name="components">

at the beginning of the file, and before the lines:

       </struct>
       <list name="plugins">

The template file is indented to make it easier to notice if you add a component in the middle of another component. This is solely for the benefit of users. Gale does not pay attention to indentation when reading the files.

Adding Variables to the Template File

When you are instructed to add a variable, you must add it at the end of the file before the closing line:

      </StGermainData>

Finished versions of all of these examples are found in input/cookbook.

Tutorial 1: Viscous Material

This example simply fills up the computational domain with a single viscous material. It is a valid input file, but will not run as nothing is moving. This file mainly serves as the basis for subsequent examples.

1. First, copy template.xml to myviscous.xml to edit as follows.
2. Add in a material. The simplest variety is a purely viscous material, so add a box covering the whole domain. (Note: Default parameters for the box, e.g., minX, maxX, minY, etc., are already defined in template.xml.):

         <struct name="boxShape">
         <param name="Type">Box</param>
         <param name="startX">minX</param>
         <param name="endX">maxX</param>
         <param name="startY">minY</param>
         <param name="endY">maxY</param>
         <param name="startZ">minZ</param>
         <param name="endZ">maxZ</param>
         </struct>
   

3. Then set the material's viscosity. (Remember that Gale has no internal knowledge of units, so if you think of everything in cgs, then this implies a viscosity of 1 g/cm^2 s.):

         <struct name="backgroundViscosity">
         <param name="Type">MaterialViscosity</param>
         <param name="eta0">1.0</param>
         </struct>
   

4. Finally, you create the material, using the components just created (the storeViscosity and storeStress parameters are standard components that enable you to get the viscosity and stress information on each particle):

         <struct name="viscous">
         <param name="Type">RheologyMaterial</param>
         <param name="Shape">boxShape</param>
         <param name="density">1.0</param>
           <list name="Rheology">
           <param>backgroundViscosity</param>
           <param>storeViscosity</param>
           <param>storeStress</param>
           </list>
         </struct>
   

5. Save this file, as it will be the basis for other examples that follow.

You can compare your result with the worked example in the file input/cookbook/viscous.xml.

Tutorial 2: Viscous Material in Simple Extension

The input file you created in Tutorial 1 is valid, but nothing moves, so Gale will output errors if you try to run it. In this next example, you will make the material extend by having the right boundary move.

1. Copy myviscous.xml to myviscous_extension.xml.
2. Make the right boundary move by changing the line after this section:

         <param name="type">WallVC</param>
         <param name="wall">right</param>
         <list name="variables">
            <struct>
            <param name="name">vx</param>
            <param name="type">double</param>
   

from <param name="value">0.0</param> to <param name="value">1.0</param>

You can now run this example, and the output will go into the directory output.template. If you want to run in 3D, you only need to change the line after:

      <param name="outputPath">./output.template</param> 

from <param name="dim">2</param> to <param name="dim">3</param>

A worked example is at input/cookbook/viscous_extension.xml. A visualization of the strain rate invariant and velocity (see Section 4.3.1 in the Gale User Manual) is shown in Figure 1 below

The banding is a numerical artifact that arises from having a finite number of particles per cell. This example generates no topography, since the material is stretched uniformly.

Tutorial 3: Viscous Material with Complex Boundaries

Another exercise is to make the bottom boundary move differently, and not just have the material slide along. In particular, this example will simulate a box like in Figure 2 (below), where the bottom right side of the box moves, but the viscous material sticks to the bottom left.

1. First, copy myviscous_extension.xml to myviscous_split.xml
2. Modify the bottom boundary condition of WallVC to the following (this makes the velocity of the bottom boundary a step function):

         <struct>
         <param name="type">WallVC</param>
         <param name="wall">bottom</param>
         <list name="variables">
           <struct>
           <param name="name">vy</param>
           <param name="type">double</param>
           <param name="value">0.0</param>
           </struct>
           <struct>
           <param name="name">vx</param>
           <param name="type">func</param>
           <param name="value">StepFunction</param>
           </struct>
         </list>
         </struct> 
   

3. You must also specify the parameters of the step function by adding these variables to the end of the file (just before </StGermainData>). Warning: Do not add them in the list named "variables":

       <param name="StepFunctionLowerOffset">1.0</param>
       <param name="StepFunctionUpperOffset">1.0</param>
       <param name="StepFunctionValue">1.0</param>
       <param name="StepFunctionDim">0</param>
       <param name="StepFunctionLessThan">False</param>
   

A worked example is in the file input/cookbook/viscous_split.xml. A visualization of the strain rate invariant and velocity (see Section 4.3.1 in the Gale User Manual) shown in Figure 3 below shows that strain rate is concentrated around the step function in the bottom velocity boundary. Notice the development of a basin above the discontinuity. The ability to track the development of topography on the free surfaces is one of the strengths of Gale.

Tutorial 4: Viscous Material with Inflow/Outflow Boundaries

This example implements a different kind of boundary condition, where material flows in one side and out another as in Figure 4 below. The current example is not intended to be geologically realistic in any sense, but is meant to illustrate the enormous flexibility we have in the development of complex boundary conditions. This type of boundary condition is useful for subduction models, an example of which is in input/subduction.xml.

1. Copy the file myviscous.xml that you created in Tutorial 1 to myviscous_inflow.xml.
2. Then, add the following lines after the wrapTop line so that Gale keeps the left and bottom sides fixed:

       <param name="staticLeft">True</param>
       <param name="staticBottom">True</param>
   

3. Now specify the velocities on the boundaries using the StepFunctionProduct functions. For the left boundary, modify the left WallVC to:

       <param name="type">WallVC</param>
       <param name="wall">left</param>
       <list name="variables">
         <struct>
           <param name="name">vx</param>
           <param name="type">func</param>
           <param name="value">StepFunctionProduct3</param>
         </struct>
       </list>
   

4. Add the variables at the end of the file (just before </StGermainData>):

       <param name="StepFunctionProduct3Start">0.1</param>
       <param name="StepFunctionProduct3End">0.2</param>
       <param name="StepFunctionProduct3Value">1</param>
   

5. For the bottom boundary, modify the bottom WallVC to:

       <param name="type">WallVC</param>
       <param name="wall">bottom</param>
       <list name="variables">
         <struct>
           <param name="name">vy</param>
           <param name="type">func</param>
           <param name="value">StepFunctionProduct2</param>
         </struct>
         <struct>
           <param name="name">vx</param>
           <param name="type">func</param>
           <param name="value">StepFunctionProduct1</param>
         </struct>
       </list>
   

6. Add the variables to the end of the file (just before </StGermainData>):

       <param name="StepFunctionProduct1Start">0.9</param>
       <param name="StepFunctionProduct1End">1.1</param>
       <param name="StepFunctionProduct1Value">1.0</param>
       <param name="StepFunctionProduct2Start">0.9</param>
       <param name="StepFunctionProduct2End">1.1</param>
       <param name="StepFunctionProduct2Value">-1.0</param>
   

7. Finally, you must alter the way that Gale creates particles. The inflow boundary condition will naturally create a space devoid of particles. Gale then creates new particles to fill that void. Normally, Gale looks at nearby particles and replicates them. However, nearby material has already changed a little from the boundary, so replicating them will not give the new particles the correct properties. To fix that, create a thin layer next to the boundary where material is created anew. To do that, first create this shape:

       <struct name="leftBoundaryShape">
         <param name="Type">Box</param>
         <param name="startX">minX</param>
         <param name="endX">0.1</param>
         <param name="startY">minY</param>
         <param name="endY">maxY</param>
         <param name="startZ">minZ</param>
         <param name="endZ">maxZ</param>
       </struct>
   

8. Then instruct the particle splitting routine to use this shape by adding
   <param name="originalParticleShape">leftBoundaryShape</param> after:

        <struct name="splittingRoutine">
          <param name="Type">ReseedSplitting</param>
          <param name="idealParticleCount">particlesPerCell</param>
   

A worked example is in the file input/cookbook/viscous_inflow.xml. A visualization of the strain rate invariant and velocity (see Section 4.3.1 in the Gale User Manual) is shown in Figure 5 below.

Additional tutorials are in Chapter 5 of the Gale User Manual