Contents

• Installation
  • Required Software
  • Supported Architectures
  • Checkout Procedure
  • Directory Structure
  • Getting Help
  
  
• Compilation
  • Creating a Configuration
    • Configuration Options
    • Available Options
    • Compiling with Extra Packages
    • File Layout
  • Building and Administering a Configuration
    • gmake Targets for Building and Administering Configurations
    • Compiling in Thorns
    • Notes and Caveats
    • gmake Options for Building Configurations
  • Other gmake Targets
  • Testing
  
  
• Running Cactus
  • Command-Line Options
  • Parameter File Syntax
  • Thorn Documentation
  
  
• Getting and Looking at Output
  • Screen Output
  • Output
  • Checkpointing/Recovery
  
  
• Overview
• Thorn Concepts
  • Thorns
  • Arrangements
  • Implementations
  
  
• Anatomy of a Thorn
  • Thorns
  • Creating a Thorn
  • Configuring your Thorn
    • General Syntax of CCL Files
    • The interface.ccl File
    • The param.ccl File
    • The schedule.ccl File
    • The configuration.ccl
  • Naming Conventions for Source Files
  • Adding Source Files
    • make.code.defn based thorn building
    • Makefile based thorn building
    • Other makefile variables
  
  
• Cactus Variables
  • Data Type
  • Group Types
  • Timelevels
  • Size and Distrib
  • Ghost Zones
  • Staggering
  • Information about Grid Variables
    • Group Information
  
  
• Cactus Parameters
  • Types and Ranges
    • Int
    • Real
    • Keyword
    • Boolean
    • String
  • Scope
  • Steerable
  
  
• Scheduling
  • Schedule Bins
  • Groups
  • Schedule Options
  • The Schedule Block
  • How Cactus Calls Scheduled Functions
  
  
• Writing a Thorn
  • Thorn Programming Languages
  • What the Flesh Provides
    • Fortran Routines
    • C Routines
    • Cactus Variables
    • Cactus Data Types
    • Staggering
  • Parallelisation
  
  
• Cactus Application Interfaces
  • Coordinates
    • Registering Coordinates and Coordinate Properties
    • Using Coordinates
  • I/O
  • Interpolation Operators
  • Reduction Operators
  
  
• Completing a Thorn
  • Commenting Source Code
  • Providing Runtime Information
  • Error Handling, Warnings and Code Termination
  • Adding Documentation
    • README
    • Contribution to Thorn Guide
  • Adding a Test Suite
    • Best Practices for Test Suites
  
  
• Advanced Thorn Writing
  • Using Cactus Timers
    • What are Timers?
    • Timing Calls
    • How to Insert Timers in your Code
  • Include Files
  • Memory Tracing
    • Activating Memory Tracing
    • Using Memory Tracing
  • Calls between Different Programming Languages
    • Calling C Routines from Fortran
    • String Arguments from Fortran
    • Calling Fortran Routines from C
  • Function aliasing
    • Using an Aliased Function
    • Providing a Function
    • Conventions and Restrictions
    • Examples
    • Testing Aliased Functions
  • Naming Conventions
  • General Naming Conventions
  • Data Types and Sizes
    • Fortran Thorn Writers
  
  
• Telling the Make system What to Do
  • Basic Recipe
  • Make Concepts
  • The Four Files
  • How your code is built
  
  
• Introduction
• Key/Value Tables
  • Motivation
  • The Basic Idea
  • A Simple Example
  • Arrays as Table Values
  • Character Strings
  • Convenience Routines
  • Table Iterators
  • Multithreading and Multiprocessor Issues
  • Metadata about All Tables
  
  
• Introduction
• Concepts and Terminology
  • Overloading and Registration
    • Overloading
    • Registration
  • GH Extensions
  • I/O Methods
  
  
• GH Extensions
• Overloadable and Registerable Functions in Main
• Overloadable and Registerable Functions in Comm
• Overloadable and Registerable Functions in I/O
• Drivers
  • Anatomy
  • Startup
  • The GH Extension
  • Memory Functions
    • En/Disable Group Storage
    • En/Disable Group Comm
  
  
• I/O Methods
  • I/O Method Registration
  • Periodic Output of Grid Variables
  • Triggered Output of Grid Variables
  • Unconditional Output of Grid Variables
  
  
• Checkpointing/Recovery Methods
  • Checkpointing Invocation
  • Recovery Invocation
  
  
• Clocks for Timing
• Glossary
• Configuration File Syntax
  • General Concepts
  • interface.ccl
    • Header block
    • Include files
    • Function aliasing
    • Variable Blocks
  • param.ccl
    • Parameter Data Scoping Items
    • Parameter Object Specification Items
  • schedule.ccl
    • Assignment Statements
    • Schedule Blocks
    • Conditional Statements
  • configuration.ccl
    • Configuration Scripts
  
  
• Schedule Bins
• Flesh Parameters
  • Private Parameters
  • Restricted Parameters
  
  
• Using GNATS
• Using CVS
  • Essential CVS Commands
  • CVS Options
  • CVS Examples
  • Checking Out Flesh and Thorns with CVS
  
  
• Using Tags
  • Tags with Emacs
  • Tags with vi
  
  
• ThornLists

pt

Preface

This document is a complete guide to using and developing with the Cactus Code. Please report omissions, errors, or suggestions to any of our contact addresses below.

Overview of documentation

Part A: Installation and Running.

A description of required hardware and software and an installation guide for Cactus. Describes how to check the installation with Cactus test suites.

Part B: Application Thorn Writing.

An introduction to thorn concepts and description of how to create, write and maintain application thorns. Explanation of use of the programming interface to take advantage of parallelism and modularity.

Part C: Utility Routines.

A discussion of low-level utility routines available in Cactus, such as key/value tables.

Part D: Infrastructure Thorn Writer's Guide.

A more advanced discussion of user supplied infrastructure routines such as additional output routines, drivers, etc.

Part E: Appendices.

These contain a description of the Cactus Configuration Language, a glossary, and other odds and ends, such as how to use GNATS and TAGS.

Related topics are discussed in separate documents including:

Reference Manual

Contains detailed descriptions of the functions provided by the Cactus flesh API, along with other reference material.

Typographical Conventions

Typewriter

Is currently used for everything you type, for program names, and code extracts.

< ... >

Indicates a compulsory argument.

[ ... ]

Indicates an optional argument.

|

Indicates an exclusive or.

How to Contact Us

Please let us know of any errors or omissions in this guide, as well as suggestions for future editions. These can be reported via our bug tracking system at http://www.cactuscode.org, or via email to cactusmaint@cactuscode.org. Alternatively, you can write to us at

The Cactus Team
Center for Computation & Technology
216 Johnston Hall
Louisiana State University
Baton Rouge, LA 70803
USA

Acknowledgements

Hearty thanks to all those who have helped with documentation for the Cactus Code. Special thanks to those who struggled with the earliest sparse versions of this guide and sent in mistakes and suggestions, in particular John Baker, Carsten Gundlach, Ginny Hudak-David, Sai Iyer, Paul Lamping, Nancy Tran and Ed Seidel.

Installation and Running 2#2 3#3