Final Report on CIG Workshop on Gale Development 

A two-day workshop held at the California Institute of Technology, August 5-6, 2009, provided advanced training in Gale use, capabilities, and code structure. The workshop was sponsored by the CIG Long-Term Tectonics Working Group and led by Walter Landry of CIG, with additional presentations by Steve Quenette of the Victoria Partnership for Advanced Computing and Louis Moresi of Monash University.


The purpose of the workshop was to provide users with advanced instruction in Gale, beyond that contained in the introductory training sessions previously taught by the Gale development team. Specifically, the workshop was intended to expose users to the deeper structure of the code and to give users tools to modify the code to enhance existing capabilities or add new ones. In this way, the workshop was intended to begin a process in which the long-term tectonics community could treat Gale as less of a ‘black box’ and thus accelerate the development process as more users vet and test the code.

Instructional aspects of the workshop focused on 1) Gale code structure, including the relevant aspects of the underlying StGermain and Underworld software packages; 2) a detailed examination of the Gale input file; and 3) critical assessment of Gale’s capabilities as informed by the combined modeling experience of the workshop participants. Selection of these topics was community driven, established by consensus of the participants prior to the workshop.


The workshop was designed for geoscientists working in geodynamic modeling of long-term tectonic processes with a stated interest in becoming involved in Gale development at the level of contributing new plugins or components. Such community-driven contributions often result from the need for users to tweak or enhance the code beyond the initial development design in order to investigate specific science problems. In keeping with this intent, the workshop was highly focused and had a relatively small audience of 10 participants from 8 different institutions. These participants included 5 academic faculty, 1 postdoctoral scholar, 1 graduate student, and scientists from CIG and VPAC who led the discussions.


The first day of the workshop began with a presentation by Landry that summarized Gale’s existing capabilities, including Inflow/Outflow boundary conditions, the use of tracers, inclusion of isostasy, and various rheologies. This was followed by a brief discussion of future directions, including the planned merging of Gale with Underworld and tentative plans for development of a new AMR code (separate from Gale). The remainder of the morning session was devoted to an extensive presentation and discussion of the Gale code structure, with an emphasis on which aspects of the program were located within the Gale source code and which are located within StGermain, StgFEM, and Underworld. This presentation prompted many questions and much discussion, leading Moresi to give a presentation about the PIC modeling methodology, how it is implemented in Underworld, reasons for choosing this modeling method, and the advantages and limitations of the PIC approach. Participants are in agreement that this discussion of code structure and the brief explanation of the numerical procedure by Moresi were extremely useful and accomplished a primary goal of making Gale seem less like a “black box.” Landry also gave a presentation on how to use a debugger to better understand what Gale is doing during various stages of a model run.

The afternoon session was intended to be split between a discussion of the Input File format and Output File Formats. However, the discussion of the Input File format took the entire afternoon. Two issues dominated the discussion. First, participants were in agreement that the XML format is confusing to many new users and that it is unclear what many, if not most, of the lines in the Input File do. Landry largely solved this problem by walking through each line, explaining its function and how that functionality related to information requested by the Gale-specific part of the code, the underlying StGermain, StgFEM, and Underworld packages, and interdependencies between different parts of the Input File. Landry also clarified which parts of the input file are largely static (setting up the basic Gale Stokes problem via invocation of the relevant parts of Underworld, StGermain, and StgFEM and thus not requiring changes between different models) and which parts require the users attention (being model specific – i.e., definition of rheologies, boundary and initial conditions, and model geometry).

This presentation was also regarded as an important success of the workshop, largely accomplishing one of the primary goals of developing expertise amongst the participants in using the Input File to design complex models that speak to their varied and individual science interests. An extensive impromptu discussion ensued concerning the desirability of moving the static parts of the Input File elsewhere so as to make it less confusing to new users. One argument put forward was that it would make the Input File more transparent if users saw only those parts that dealt specifically with model design and parameterization, whilst those parts that set up the basic Stokes problem could be moved into a separate file. A counter argument was that including all parts in one Input File promoted better understanding of how Gale works if the user were properly educated on what each part does. This discussion included a suggestion of developing a tutorial book that described the Input File in detail, but it was noted that such an undertaking would require time from the development team that might better be spent on software development.

It was also noted that having all parts in one file enabled the savvy user to invoke other component choices available through Underworld that might be useful for a specific modeling project that was not envisioned during development of Gale. Landry pointed out that the savvy user would have access to the “hidden” input file and could always do such tinkering if needed. No consensus was reached and the discussion was ended due to a desire to move on to other topics. Moresi pointed out that many of the StGermain- and Underworld-specific aspects of the input file are documented in the Underworld Component Codex. Most Gale users appear to be unaware of the Codex and the workshop participants found this documentation to greatly enhance their understanding of the code, so it is suggested that there be a link to the Codex in the Gale Manual.

A short evening meeting was held prior to supper to re-examine the agenda for Day 2. It was decided that the discussion of Output File formats be eliminated in favor of adding a detailed tutorial on how to create components and plugins and a presentation by Quenette on a melt extraction component under development. Also at this meeting, participants identified a need to set up a Gale wiki where users could share examples of working and failed models. An intensive discussion of how isostasy is handled in Gale took place at this meeting (and continued at supper and the following afternoon).

The morning of the second day of the workshop was devoted to completing the examination of the Input File, with an emphasis on how to change the model-specific lines to create new and more complex models beyond those contained in the cookbook examples. This was followed with a tutorial on how to modify Gale to create new Standard Condition Functions, Rheologies, how the existing Surface Processes plugin works and how it could be modified to include user-specified surface process models. The afternoon session began with a presentation and hands-on exercise in adding plugins and components. This emphasized using existing plugins and components as templates and modifying them to create the new component or plugin desired by the user. Quenette then demonstrated the melt code that is in a beta stage and described the physical and computational basis and where it can be added into the existing Gale release if participants wish to experiment with it. A copy of the as yet unreleased code was provided to the workshop participants. The final afternoon activity was devoted to building a new and geologically interesting model “from scratch”. Participants chose an example of a convergent margin, basing the model on a figure from a Sean Willett paper. Constructing the model was somewhat delayed while a lively discussion took place concerning appropriate boundary conditions, how/if the Willett model could be implemented in Gale, and, continuing the discussion of the previous night, how isostasy should be dealt with. With a half hour remaining, the participants then asked Landry to build and run the model. This was both entertaining (due to the short time Landry was allotted) and instructive as participants learned how pieces of the cookbook input files could be easily stitched together to create a new and more complex model, how new rheologies and boundary conditions could be rapidly inserted, and how various features could be turned on and off to debug the model.

The workshop ended with participants thanking Walter Landry, Steve Quenette, and Louis Moresi for their efforts. Participants agreed that the workshop was successful in achieving the goals established prior to the meeting.


  1. Participants believe that the workshop succeed in creating a core user group capable of rapidly developing substantial expertise in geodynamic modeling using Gale. It is expected that this will lead to a rapid increase in the number of science proposals and science papers based on Gale modeling studies.
  2. Participants anticipate that a number of new user-developed components and plugins will appear in the next 1-2 years invoking new Standard Condition Functions, surface process models, and melt volume calculations. It is expected that these will be distributed amongst the user community and returned to CIG for inclusion in the next Gale release if proper benchmarking can be accomplished. Alternatively, a “contribs” directory can be added to the Gale release, allowing users to build in contributed tools if they so desire. User development of these plugins can be facilitated by CIG creation of generic plugin examples that illustrate how users can build plugins that access different variables and model parameters of interest. These example plugins should clearly identify model parameters and variables of interest via comments in the XML code.
  3. Participants and developers agreed to identify a number of useful functions that can be developed into code snippets that can be used as templates for users as they develop plugins and components. One example would be: a way to average a property over all the particles within a cell and outputting that averaged quantity for all cells. These ‘toolbox’ code snippets can be made available to the user community after the group decides on what is needed. This is to happen by email exchange, likely over the CIG-Long list so that the larger community is aware.
  4. Participants noted that a spreadsheet would be useful that converts parameters and dimensions specified in common geological units into units that scale well within Gale. Moresi has since noted that Sergio Zlotnik at Monash University has recently developed such a spreadsheet and will be releasing it to the user community soon.
  5. Because there was a divided view about the complexity of the input file format, it was recommended that the current “flat file” format be kept, but that the user community develop a program or script to allow an alternative way to interface with Gale. This alternative would involve the user seeing and dealing with an abbreviated input file focused only on parameters the casual user would need to change. This short file would then be combined with another file prior to runtime to create the full flat file. Because this program or script is to be developed by the user community, it allows the current CIG input file approach intact and available for those who want to use it whilst allowing for the alternative if so desired.
  6. Two ideas about how to improve the manual came out of the workshop:
    1. The manual should include a description of the source code directory structure similar to the presentation Landry provided in the workshop.
    2. A Wiki could be started to allow users to upload their own additions to the manual and add example input files. Because this gets the user community involved in creating the manual, it is felt that over time this would lead to a manual much more suited to the user communities needs while at the same time relieving CIG personnel for much of the tasks associated with maintaining and updating the manual. Alternatively, Landry expressed willingness to accept minor additions/revision to the manual and implement them himself.
  7. Several additions to Gale functionality were considered to be high priority by workshop participants. It was recognized, however, that many of these will be implemented when Gale is merged with Underworld.
    1. The addition of elasticity (present in Underworld) to Gale is of high interest to the workshop participants and others in the community.
    2. The range of geologic problems Gale can be applied to could be significantly expanded if both the top and bottom boundaries of the model were allowed to deform. Gale currently only allows deformation of the top boundary.
    3. The VPAC plug in example for partial melts demonstrated in the workshop by Quenette is of high interest and should be added to the standard Gale code and described in the manual when it is fully tested and ready for release.


  • Eunseo Choi (Lamont Doherty Earth Observatory)
  • Todd Ehlers (University of Michigan)
  • Mark Fleherty (University of New Mexico)
  • Dennis Harry (Colorado State University)
  • Fraser Keppie (California Institute of Technology)
  • Walter Landry (CIG)
  • Louis Moresi (Monash University)
  • Mousumi Roy (University of New Mexico)
  • Steve Quenette (VPAC)
  • Jolante Van Wijke (University of Houston)
Sign In