# Citcom

CitCom (for California Institute of Technology Convection in the Mantle) is a finite element code designed to solve thermal convection problems relevant to Earth's mantle released under the GNU General Public License. Written in C, the code's latest version, CitComS, runs on a variety of parallel processing computers, including shared and distributed memory platforms.

## History

CitCom was originally written in the early 1990s by Louis Moresi (Monash U.). Although the code for three-dimensional problems was incorporated from its inception, early versions of the software only solved for time-dependent convection problems within two-dimensional Cartesian domains. Moresi's original code turned out to be incredibly modular and easily extensible. Consequently, the fundamental finite element infrastructure which Louis wrote is still in place and forms the basis for much of the code contained in the present release.
In the mid-1990s Moresi wrote versions of the code that solved the equations within three-dimensional Cartesian domains. Then Shijie Zhong (U. of Colorado, Boulder) successfully parallelized CitCom using message passing routines on a limited release Intel supercomputer. Zhong then created a spherical version of the code which he named CitComS. Lijie Han (Planetary Science Institute) then created a regional version of CitComS as well as an alternate version of message passing for an arbitrarily large number of processors. Clint Conrad (Johns Hopkins) created the first Beowulf implementations of the code, then Conrad and Eh Tan (Computational Infrastructure for Geodynamics) re-coded the message passing of the fully spherical version so that problems run on arbitrarily large numbers of processors could also be solved. A plethora of different versions of CitCom exist both on computers at the California Institute of Technology and around the world.
Consequently, by 2002, there were so many different versions of the code that some rationalization was in order. The software was migrated into a version control system and Eh Tan and Eun-seo Choi (Caltech) created a version of CitComS that generates either a fully spherical or regional model, CitcomSFull and CitcomSRegional respectively. CitComS was released to the community through the former GeoFramework project as version 1.0 and 1.1.
By 2004, in order to increase the functionality of CitComS, the developers began to reengineer the code into an object-oriented environment specifically so it could work with a Python-based modeling framework called Pyre. This release of the software, now named CitComS.py, is essentially the product of those reengineering efforts. Eh Tan was the principal developer of CitComS.py, with considerable help from Eun-seo Choi and Michael Aivazis (Caltech).
CitComS is one component of a larger collection of software encompassed by the former GeoFramework project, a collaboration between the Center for Advanced Computing Research (CACR) and the Seismological Laboratory, both at Caltech, and the Victorian Partnership for Advanced Computing in Australia. The GeoFramework project developed a suite of tools to model multi-scale deformation for Earth science problems. This effort was motivated by the need to understand interactions between the long-term evolution of plate tectonics and shorter term processes such as the evolution of faults during and between earthquakes. During 2005 and 2006 much of the remaining software developed by GeoFramework was released under a GPL license and made available from Computational Infrastructure for Geodynamics (CIG).
The second major release of CitComS (2.0) incorporated the software framework Pyre, free surface modeling methods, and stress boundary conditions on the top and bottom surfaces. In the summer of 2005, as part of the 2.0.1 release, CIG replaced the old build procedure with the GNU Build System. A subsequent release, version 2.0.2, could compile and run on 64-bit systems.
The third major release of CitComS (2.1) incorporated new features and functionality, the most important being the use of HDF5 (a parallel version of the Hierarchical Data Format). The HDF5 format allows you to deal with the massive data output created for production runs. This version accepted .cfg files on input, which are easier to create and read.
Other improvements included the incorporation of geoid calculations that had been left out of earlier releases, as well as new scripts to allow results to be visualized with MayaVi2 in addition to Generic Mapping Tools (GMT) and OpenDX. Instructions were provided on using this version as a preinstalled package on some of the NSF TeraGrid sites.
The latest release of CitComS (2.2, 3/27/07) incorporates the ability of tracing particles in the flow. The tracer code was developed by Allen McNamara and Shijie Zhong in 2004 and donated to CIG in early 2007. The tracer code has a wide range of applications in the mantle convection. It can be used in tracing the trajectory of passive particles, in delineating the top boundary of subducted slabs to define the low viscosity wedges, or in tracking the evolution of the chemical composition field.