Cylc documentation

The Cylc Suite Engine

Current release: 7.9.3

Released Under the GNU GPL v3.0 Software License

Copyright (C) NIWA & British Crown (Met Office) & Contributors.

---

Cylc (“silk”) is a workflow engine for cycling systems - it orchestrates distributed suites of interdependent cycling tasks that may continue to run indefinitely.

---

Table of Contents:

• 1. Introduction: How Cylc Works
  • 1.1. Dependence Between Tasks
    • 1.1.1. Intra-cycle Dependence
    • 1.1.2. Inter-Cycle Dependence
• 2. Cylc Screenshots
• 3. Installation
  • 3.1. Third-Party Software Packages
  • 3.2. Software Bundled With Cylc
  • 3.3. Installing Cylc
    • 3.3.1. Local User Installation
    • 3.3.2. Create A Site Config File
    • 3.3.3. Configure Site Environment on Job Hosts
    • 3.3.4. Configuring Cylc Review Under Apache
  • 3.4. Automated Tests
• 4. Cylc Terminology
  • 4.1. Jobs and Tasks
  • 4.2. Cycle Points
• 5. Workflows For Cycling Systems
  • 5.1. Cycling Workflows
  • 5.2. Parameterized Tasks as a Proxy for Cycling
  • 5.3. Mixed Cycling Workflows
• 6. Global (Site, User) Configuration Files
• 7. Tutorial
  • 7.1. User Config File
    • 7.1.1. Configure Environment on Job Hosts
  • 7.2. User Interfaces
    • 7.2.1. Command Line Interface (CLI)
    • 7.2.2. Graphical User Interface (GUI)
  • 7.3. Suite Configuration
  • 7.4. Suite Registration
  • 7.5. Suite Passphrases
  • 7.6. Import The Example Suites
  • 7.7. Rename The Imported Tutorial Suites
  • 7.8. Suite Validation
  • 7.9. Hello World in Cylc
  • 7.10. Editing Suites
  • 7.11. Running Suites
    • 7.11.1. CLI
    • 7.11.2. GUI
  • 7.12. Remote Suites
  • 7.13. Discovering Running Suites
  • 7.14. Task Identifiers
  • 7.15. Job Submission: How Tasks Are Executed
  • 7.16. Locating Suite And Task Output
  • 7.17. Viewing Suite Logs in a Web Browser: Cylc Review
  • 7.18. Remote Tasks
  • 7.19. Task Triggering
    • 7.19.1. Task Failure And Suicide Triggering
  • 7.20. Runtime Inheritance
  • 7.21. Triggering Families
  • 7.22. Triggering Off Of Families
  • 7.23. Suite Visualization
  • 7.24. External Task Scripts
  • 7.25. Cycling Tasks
    • 7.25.1. ISO 8601 Date-Time Syntax
    • 7.25.2. Inter-Cycle Triggers
    • 7.25.3. Initial Non-Repeating (R1) Tasks
    • 7.25.4. Integer Cycling
  • 7.26. Jinja2
  • 7.27. Task Retry On Failure
  • 7.28. Other Users’ Suites
  • 7.29. Other Things To Try
• 8. Suite Name Registration
  • 8.1. Suite Registration
  • 8.2. Suite Names
• 9. Suite Configuration
  • 9.1. Suite Configuration Directories
  • 9.2. Suite.rc File Overview
    • 9.2.1. Syntax
    • 9.2.2. Include-Files
    • 9.2.3. Syntax Highlighting For Suite Configuration
    • 9.2.4. Gross File Structure
    • 9.2.5. Validation
  • 9.3. Scheduling - Dependency Graphs
    • 9.3.1. Graph String Syntax
    • 9.3.2. Interpreting Graph Strings
    • 9.3.3. Graph Types
    • 9.3.4. Graph Section Headings
    • 9.3.5. Task Triggering
    • 9.3.6. Model Restart Dependencies
    • 9.3.7. How The Graph Determines Task Instantiation
  • 9.4. Runtime - Task Configuration
    • 9.4.1. Task and Namespace Names
    • 9.4.2. Root - Runtime Defaults
    • 9.4.3. Defining Multiple Namespaces At Once
    • 9.4.4. Runtime Inheritance - Single
    • 9.4.5. Runtime Inheritance - Multiple
    • 9.4.6. How Runtime Inheritance Works
    • 9.4.7. Task Execution Environment
    • 9.4.8. How Tasks Get Access To The Suite Directory
    • 9.4.9. Remote Task Hosting
  • 9.5. Visualization
    • 9.5.1. Collapsible Families In Suite Graphs
  • 9.6. Parameterized Tasks
    • 9.6.1. Parameter Expansion
    • 9.6.2. Passing Parameter Values To Tasks
    • 9.6.3. Selecting Specific Parameter Values
    • 9.6.4. Selecting Partial Parameter Ranges
    • 9.6.5. Parameter Offsets In The Graph
    • 9.6.6. Task Families And Parameterization
    • 9.6.7. Parameterized Cycling
  • 9.7. Jinja2
    • 9.7.1. Accessing Environment Variables With Jinja2
    • 9.7.2. Custom Jinja2 Filters, Tests and Globals
    • 9.7.3. Associative Arrays In Jinja2
    • 9.7.4. Jinja2 Default Values And Template Inputs
    • 9.7.5. Jinja2 Variable Scope
    • 9.7.6. Raising Exceptions
    • 9.7.7. Importing additional Python modules
  • 9.8. EmPy
  • 9.9. Omitting Tasks At Runtime
  • 9.10. Naked Dummy Tasks And Strict Validation
• 10. Task Implementation
  • 10.1. Task Job Scripts
  • 10.2. Inlined Tasks
  • 10.3. Task Messages
  • 10.4. Aborting Job Scripts on Error
    • 10.4.1. Custom Failure Messages
  • 10.5. Avoid Detaching Processes
• 11. Task Job Submission and Management
  • 11.1. Supported Job Submission Methods
    • 11.1.1. background
    • 11.1.2. at
    • 11.1.3. loadleveler
    • 11.1.4. lsf
    • 11.1.5. pbs
    • 11.1.6. moab
    • 11.1.7. sge
    • 11.1.8. slurm
    • 11.1.9. Default Directives Provided
    • 11.1.10. Directives Section Quirks (PBS, SGE, …)
  • 11.2. Task stdout And stderr Logs
  • 11.3. Overriding The Job Submission Command
  • 11.4. Job Polling
  • 11.5. Job Killing
  • 11.6. Execution Time Limit
    • 11.6.1. Execution Time Limit and Execution Timeout
  • 11.7. Custom Job Submission Methods
    • 11.7.1. An Example
    • 11.7.2. Where To Put Batch System Handler Modules
• 12. External Triggers
  • 12.1. Built-in Clock Triggers
  • 12.2. Built-in Suite State Triggers
  • 12.3. Custom Trigger Functions
    • 12.3.1. Toy Examples
  • 12.4. Current Limitations
  • 12.5. Filesystem Events?
  • 12.6. Continuous Event Watchers?
  • 12.7. Old-Style External Triggers (Deprecated)
• 13. Running Suites
  • 13.1. Suite Start-Up
    • 13.1.1. Cold Start
    • 13.1.2. Warm Start
    • 13.1.3. Restart and Suite State Checkpoints
  • 13.2. Reloading The Suite Configuration At Runtime
  • 13.3. Task Job Access To Cylc
  • 13.4. The Suite Contact File
  • 13.5. Task Job Polling
    • 13.5.1. Routine Polling
  • 13.6. Tracking Task State
    • 13.6.1. HTTPS Task Messaging
    • 13.6.2. Ssh Task Messaging
    • 13.6.3. Polling to Track Job Status
    • 13.6.4. Task Communications Configuration
  • 13.7. The Suite Service Directory
  • 13.8. File-Reading Commands
    • 13.8.1. Remote Host, Shared Home Directory
    • 13.8.2. Remote Host, Different Home Directory
    • 13.8.3. Same Host, Different User Account
  • 13.9. Client-Server Interaction
    • 13.9.1. Public Access - No Auth Files
    • 13.9.2. Full Control - With Auth Files
  • 13.10. GUI-to-Suite Interaction
  • 13.11. Remote Control
  • 13.12. Scan And Gscan
  • 13.13. Task States Explained
  • 13.14. What The Suite Control GUI Shows
  • 13.15. Network Connection Timeouts
  • 13.16. Runahead Limiting
  • 13.17. Limiting Activity With Internal Queues
  • 13.18. Automatic Task Retry On Failure
  • 13.19. Task Event Handling
    • 13.19.1. Late Events
  • 13.20. Managing External Command Execution
  • 13.21. Handling Job Preemption
  • 13.22. Manual Task Triggering and Edit-Run
  • 13.23. Cylc Broadcast
  • 13.24. The Meaning And Use Of Initial Cycle Point
    • 13.24.1. The Environment Variable CYLC_SUITE_INITIAL_CYCLE_POINT
  • 13.25. Simulating Suite Behaviour
    • 13.25.1. Proportional Simulated Run Length
    • 13.25.2. Limitations Of Suite Simulation
    • 13.25.3. Restarting Suites With A Different Run Mode?
  • 13.26. Automated Reference Test Suites
    • 13.26.1. Roll-your-own Reference Tests
  • 13.27. Triggering Off Of Tasks In Other Suites
  • 13.28. Suite Server Logs
  • 13.29. Suite Run Databases
  • 13.30. Disaster Recovery
  • 13.31. Auto Stop-Restart
  • 13.32. Alternate Suite Run Directories
  • 13.33. Sub-Suites
• 14. Suite Storage, Discovery, Revision Control, and Deployment
  • 14.1. Rose
• 15. Appendices
  • 15.1. Suite.rc Reference
    • 15.1.1. Top Level Items
    • 15.1.2. [meta]
    • 15.1.3. [cylc]
    • 15.1.4. [scheduling]
    • 15.1.5. [runtime]
    • 15.1.6. [visualization]
  • 15.2. Global (Site, User) Config File Reference
    • 15.2.1. Top Level Items
    • 15.2.2. [task messaging]
    • 15.2.3. [suite logging]
    • 15.2.4. [documentation]
    • 15.2.5. [document viewers]
    • 15.2.6. [editors]
    • 15.2.7. [communication]
    • 15.2.8. [monitor]
    • 15.2.9. [hosts]
    • 15.2.10. [suite servers]
    • 15.2.11. [suite host self-identification]
    • 15.2.12. [task events]
    • 15.2.13. [test battery]
    • 15.2.14. [cylc]
    • 15.2.15. [authentication]
  • 15.3. Gcylc GUI (cylc gui) Config File Reference
    • 15.3.1. Top Level Items
    • 15.3.2. [themes]
  • 15.4. Gscan GUI (cylc gscan) Config File Reference
    • 15.4.1. Top Level Items
  • 15.5. Remote Job Management
    • 15.5.1. SSH-free Job Management?
    • 15.5.2. SSH-based Job Management
    • 15.5.3. A Concrete Example
    • 15.5.4. Other Use of SSH in Cylc
  • 15.6. Command Reference
    • 15.6.1. Help
    • 15.6.2. Command Categories
    • 15.6.3. Commands
  • 15.7. The gcylc Graph View
  • 15.8. Cylc README File
  • 15.9. Cylc INSTALL File
  • 15.10. Cylc Development History - Major Changes
  • 15.11. Cylc 6 Migration Reference
    • 15.11.1. Timeouts and Delays
    • 15.11.2. Runahead Limit
    • 15.11.3. Cycle Time/Cycle Point
    • 15.11.4. Cycling
    • 15.11.5. No Implicit Creation of Tasks by Offset Triggers
  • 15.12. Known Issues
    • 15.12.1. Current Known Issues
    • 15.12.2. Notable Known Issues
  • 15.13. GNU GENERAL PUBLIC LICENSE v3.0
• 16. Suite Design Guide
  • 16.1. Introduction
  • 16.2. Style Guidelines
    • 16.2.1. Tab Characters
    • 16.2.2. Trailing Whitespace
    • 16.2.3. Indentation
    • 16.2.4. Comments
    • 16.2.5. Titles, Descriptions, And URLs
    • 16.2.6. Line Length And Continuation
    • 16.2.7. Task Naming Conventions
    • 16.2.8. Rose Config Files
  • 16.3. Basic Principles
    • 16.3.1. UTC Mode
    • 16.3.2. Fine Or Coarse-Grained Suites
    • 16.3.3. Monolithic Or Interdependent Suites
    • 16.3.4. Self-Contained Suites
    • 16.3.5. Task Host Selection
    • 16.3.6. Task Scripting
    • 16.3.7. Rose Apps
    • 16.3.8. Rose Metadata Compliance
    • 16.3.9. Task Independence
    • 16.3.10. Clock-Triggered Tasks
    • 16.3.11. Rose App File Polling
    • 16.3.12. Task Execution Time Limits
    • 16.3.13. Restricting Suite Activity
    • 16.3.14. Suite Housekeeping
    • 16.3.15. Complex Jinja2 Code
    • 16.3.16. Shared Configuration
    • 16.3.17. Automating Failure Recovery
    • 16.3.18. Include Files
  • 16.4. Efficiency And Maintainability
    • 16.4.1. The Task Family Hierarchy
    • 16.4.2. Generating Tasks Automatically
    • 16.4.3. Optional App Config Files
  • 16.5. Portable Suites
    • 16.5.1. The Jinja2 SITE Variable
    • 16.5.2. Site Include-Files
    • 16.5.3. Site-Specific Graphs
    • 16.5.4. Inlined Site-Switching
    • 16.5.5. Site-Specific Suite Variables
    • 16.5.6. Site-Specific Optional Suite Configs
    • 16.5.7. Site-Agnostic File Paths in App Configs
    • 16.5.8. Site-Specific Optional App Configs
    • 16.5.9. An Example
    • 16.5.10. Collaborative Development Model
    • 16.5.11. Research-To-Operations Transition
  • 16.6. Roadmap
    • 16.6.1. List Item Override In Site Include-Files
    • 16.6.2. UM STASH in Optional App Configs
    • 16.6.3. Modular Suite Design