Cactus Users Guide

1 Cactus Users ' Guide Contents A Introduction A1. A1 Getting Started A2. Obtaining Cactus .. A2. Directory Structure .. A2. Compiling a Cactus application .. A3. Creating a Configuration .. A3. Running a Cactus application .. A4. A2 Getting and looking at output A5. Screen output .. A5. File output .. A6. A3 Checkpointing/Recovery A7. A4 Reporting bugs A8. B Additional notes B1. B1 Installation B2. Required Software .. B2. Supported Architectures .. B3. Note .. B4. B2 Compilation B5. Configuration Options .. B5. Available Options .. B6. Compiling with Extra Packages.

2 B10. MPI: Message Passing Interface .. B10. HDF5: Hierarchical Data Format version 5 .. B12. LAPACK: Linear Algebra PACKage .. B12. PETSc: Portable, Extensible Toolkit for Scientific Computation .. B12. Pthreads: POSIX threads .. B13. File Layout .. B13. Building and Administering a Configuration .. B14. gmake Targets for Building and Administering Configurations .. B14. Compiling in Thorns .. B15. Notes and Caveats .. B16. gmake Options for building configurations .. B16. Other gmake Targets .. B16. Testing .. B17. i B3 Runtime options B18.

3 Command-Line Options .. B18. Parameter File Syntax .. B20. Thorn Documentation .. B22. B4 Getting and Looking at Output B23. Screen Output .. B23. Output .. B24. C Thorn Writing C1. C1 Application thorns C3. Thorn Concepts .. C3. Thorns .. C3. Arrangements .. C3. Implementations .. C4. Anatomy of a Thorn .. C4. Thorns .. C4. Creating a Thorn .. C5. Configuring your Thorn .. C5. Naming Conventions for Source Files .. C13. Adding Source Files .. C14. Cactus Variables .. C16. Data Type .. C16. Group Types .. C17. Timelevels .. C17. Size and Distrib.

4 C18. Ghost Zones .. C18. Staggering .. C19. Information about Grid Variables .. C20. Cactus Parameters .. C21. Types and Ranges .. C21. Scope .. C23. Steerable .. C23. Scheduling .. C23. Schedule Bins .. C24. Groups .. C24. Schedule Options .. C24. The Schedule Block .. C25. How Cactus Calls Scheduled Functions .. C26. Writing a Thorn .. C26. Thorn Programming Languages .. C26. What the Flesh Provides .. C26. Parallelisation .. C37. Cactus Application Interfaces .. C37. Coordinates .. C37. I/O .. C41. Interpolation Operators .. C42. Reduction Operators.

5 C43. Completing a Thorn .. C50. Commenting Source Code .. C50. ii Providing Runtime Information .. C50. Error Handling, Warnings and Code Termination .. C51. Adding Documentation .. C53. Adding a Test Suite .. C55. Advanced Thorn Writing .. C57. Using Cactus Timers .. C57. Include Files .. C59. Memory Tracing .. C61. Calls to different language .. C62. Function aliasing .. C65. Naming Conventions .. C68. General Naming Conventions .. C68. Data Types and Sizes .. C68. Telling the Make system What to Do .. C71. Basic Recipe .. C71. Make Concepts.

6 C71. The Four Files .. C71. How your code is built .. C71. C2 Infrastructure Thorns C72. Concepts and Terminology .. C72. Overloading and Registration .. C72. GH Extensions .. C73. I/O Methods .. C73. GH Extensions .. C73. Overloadable and Registerable Functions in Main .. C73. Overloadable and Registerable Functions in Comm .. C74. Overloadable and Registerable Functions in I/O .. C74. Drivers .. C74. Anatomy .. C74. Startup .. C74. The GH Extension .. C75. Memory Functions .. C78. I/O Methods .. C79. I/O Method Registration .. C80. Periodic Output of Grid Variables.

7 C80. Triggered Output of Grid Variables .. C80. Unconditional Output of Grid Variables .. C81. Checkpointing/Recovery Methods .. C81. Checkpointing Invocation .. C81. Recovery Invocation .. C82. Clocks for Timing .. C83. D Appendices D1. D1 Glossary D3. D2 Configuration File Syntax D8. General Concepts .. D8.. D8. Header Block .. D8. iii Include Files .. D9. Function Aliasing .. D9. Variable Blocks .. D10.. D12. Parameter Data Scoping Items .. D12. Parameter Object Specification Items .. D12.. D14. Assignment Statements .. D14. Schedule Blocks.

8 D15. Conditional Statements .. D17.. D18. Configuration Scripts .. D19. D3 Utility Routines D20. Introduction .. D20. Key/Value Tables .. D20. Motivation .. D20. The Basic Idea .. D20. A Simple Example .. D21. Arrays as Table Values .. D22. Character Strings .. D23. Convenience Routines .. D24. Table Iterators .. D25. Multithreading and Multiprocessor Issues .. D25. Metadata about All Tables .. D25. D4 Schedule Bins D26. D5 Flesh Parameters D29. Private Parameters .. D29. Restricted Parameters .. D30. D6 Using TRAC D31. D7 Using SVN D33.

9 Essential SVN Commands .. D33. D8 Using Tags D35. Tags with Emacs .. D35. Tags with vi .. D36. 4. Preface This document contains a quick-start Guide to installing and running a Cactus application. In subsequent chapters, it provides more detailed information on advanced user 's topics, as well as an introduction to thorn writing. Please report omissions, errors, or suggestions to any of our contact addresses below. Overview of documentation Part A: Introduction to Cactus . A Guide through the process of obtaining and installing Cactus and running a simple example application with it.

10 Part B: Additional Notes. A more in-depth description of required hardware and software, along with config- uration, installation and running options. Describes how to check the installation with Cactus test suites. Part C: Thorn Writing. An introduction to thorn concepts and description of how to create, write and main- tain application thorns. Explanation of use of the programming interface to take advantage of parallelism and modularity. This is followed by a more advanced dis- cussion of user supplied infrastructure routines such as additional output routines, drivers, etc.