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 Size
  • Staggering
  • Information about Grid Variables
    • Group Information
  
  
• Cactus Parameters
  • Types and Ranges
    • Integer
    • 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
  • IO
  • 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
  
  
• 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
  • IO Methods
  
  
• GH Extensions
• Overloadable and Registerable Functions in Main
• Overloadable and Registerable Functions in Comm
• Overloadable and Registerable Functions in IO
• 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 will eventually be a complete guide to using and developing with the Cactus Code. However, it is currently under development, so please be patient if you can't find what you need. Please report omissions, errors, or suggestions to and of our contact addresses below, and we will try and fix them as soon as possible.

Overview of documentation

This guide covers the following topics

Part A: Installation and Running.

We give an overview of required hardware and software and talk you through the installation of a working Cactus tool kit. You will be able to verify the correct installation with our test suite technology.

Part B: Application Thorn Writing.

We introduce thorn concepts and describe all you need to know for creating, writing and maintaining application thorns. You will learn how to use the programming interface to take advantage of parallelism and modularity.

Part C: Utility Routines.

This part discusses low-level utility routines available in Cactus, such as key/value tables.

Part D: Infrastructure Thorn Writer's Guide.

In this more advanced part, we talk about user supplied infrastructure routines such as additional output routines, drivers, etc. [This part is not yet complete, and is currently under construction.]

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 or TAGS.

Other topics to be discussed in separate documents include:

Reference Manual

This contains ``manual pages'' for all the APIs provided by the Cactus flesh, along with other reference material.

Computational Thorn Guide

This will contain details about the arrangements and thorns making up the standard Cactus Computational Tool Kit.

Relativity Thorn Guide

This will contain details about the arrangements and thorns making up the Cactus Relativity Tool Kit, one of the major motivators, and still the driving force, for the Cactus Code.

Flesh Maintainers Guide

This will contain all the gruesome details about the inner workings of Cactus, for all those who want or need to expand or maintain the core of Cactus.

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, write to us at

The Cactus Team
Albert Einstein Institute
Max Planck Institute for Gravitational Physics
Am Mühlenberg 1
D-14476 Golm
Germany

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 1#1 2#2