Skip to content

Commit e589cb4

Browse files
rljacobrljacob
authored
Merge pull request #4940 from ESMCI/rljacob/add-agentsmd
Add AGENTS.md for CIME. Also add a hidden CLAUDE.md file that includes it since Claude Code refuses to follow the standard. This was generated by Claude Code init function operating on a fresh checkout of CIME
2 parents 7997bb9 + ca71253 commit e589cb4

3 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
@../AGENTS.md
6+
7+
# Important
8+
This CLAUDE.md file is maintained by the project maintainers and should not be
9+
modified by /init or any automated process. Do not overwrite, replace, or
10+
regenerate this file. If asked to run /init, warn the user that it will
11+
overwrite the project's curated AI instructions.

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,13 @@ libraries
2929
share
3030
test_coverage/**
3131
*.bak
32+
33+
# AI coding tool local state
34+
.gemini/
35+
.codex/
36+
37+
# Special for Claude Code user config
38+
.claude/*
39+
!.claude/CLAUDE.md
40+
CLAUDE.md
41+
CLAUDE.local.md

‎AGENTS.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI agents when working with code in this repository.
4+
5+
## Note to AI agents
6+
7+
This AGENTS.md is maintained by the CIME project. Do not overwrite or
8+
regenerate this file with init commands.
9+
10+
## Note to claude code users
11+
12+
A CLAUDE.md file is in .claude directory. It includes
13+
this file. Ignore tips to run init.
14+
15+
## Project Overview
16+
17+
CIME (Common Infrastructure for Modeling the Earth) provides a Case Control System (CCS) for configuring, compiling, and executing Earth System Models, plus a framework for system testing. CIME is a Python-based infrastructure currently used by CESM, E3SM, NorESM and other models. It does NOT contain model source code itself, but provides the infrastructure to manage model runs.
18+
19+
## Running Tests
20+
21+
### Unit and System Tests
22+
23+
From the repository root, run tests using either:
24+
25+
```bash
26+
# Using pytest (recommended)
27+
pytest CIME/tests
28+
29+
# Run specific test file
30+
pytest CIME/tests/test_unit_foo.py
31+
32+
# Run specific test class
33+
pytest CIME/tests/test_unit_foo.py::TestClass
34+
35+
# Run specific test case
36+
pytest CIME/tests/test_unit_foo.py::TestClass::test_method
37+
```
38+
39+
Test files follow a naming convention:
40+
- Unit tests: `test_unit_*.py`
41+
- System tests: `test_sys_*.py`
42+
43+
### Pre-commit Hooks
44+
45+
Before committing, always run:
46+
47+
```bash
48+
pip install pre-commit
49+
pre-commit run -a
50+
```
51+
52+
This runs:
53+
- `black` formatter on CIME code
54+
- `pylint` with project-specific configuration
55+
- XML validation on config files
56+
- End-of-file and trailing whitespace checks
57+
58+
## Code Quality
59+
60+
- Code is formatted with `black`
61+
- Linted with `pylint` (see `.pre-commit-config.yaml` for disabled checks)
62+
- Python 3.9+ required
63+
- Follow PEP8 style guidelines
64+
65+
## Key Architecture Concepts
66+
67+
### Case Control System (CCS)
68+
69+
The heart of CIME is the `Case` class (`CIME/case/case.py`), which manages all interactions with a CIME case. The Case class coordinates between:
70+
71+
1. **Config XML Classes** (readonly) - Located in `CIME/XML/`, these read CIME distribution config files like `config_*.xml`. Python classes are named after the XML they read (e.g., `Machines` reads machine configs).
72+
73+
2. **Env XML Classes** (read/write) - Also in `CIME/XML/`, these manage case-specific `env_*.xml` files. Classes are named `Env*` (e.g., `EnvRun`, `EnvBuild`).
74+
75+
The Case class contains an array of Env classes and uses Config classes to populate them during case creation/configuration.
76+
77+
### Directory Structure
78+
79+
```
80+
CIME/
81+
├── case/ # Case control modules (setup, run, submit, etc.)
82+
├── XML/ # XML parsers for config and env files
83+
├── SystemTests/ # System test implementations (ERS, ERT, etc.)
84+
├── Tools/ # Case manipulation tools (xmlchange, xmlquery, etc.)
85+
├── scripts/ # Top-level user-facing scripts
86+
├── data/ # Config files, XML schemas
87+
├── tests/ # Unit and system tests
88+
├── BuildTools/ # Build system utilities
89+
└── non_py/ # Non-Python components (C/Fortran)
90+
91+
scripts/
92+
├── create_newcase # Create new case
93+
├── create_test # Create and run tests
94+
├── create_clone # Clone existing case
95+
├── query_config # Query available configurations
96+
└── query_testlists # Query test lists
97+
98+
tools/
99+
└── mapping/ # Grid mapping file generation tools
100+
```
101+
102+
### Common Workflows
103+
104+
**Create a case** (requires machine configuration):
105+
```bash
106+
./scripts/create_newcase --case CASENAME --compset COMPSET --res GRID [--machine MACHINE]
107+
```
108+
109+
**Create and run tests**:
110+
```bash
111+
./scripts/create_test TESTNAME
112+
./scripts/create_test TESTNAME1 TESTNAME2 ...
113+
./scripts/create_test -f TESTFILE # from file
114+
```
115+
116+
**Query configurations**:
117+
```bash
118+
./scripts/query_config --compsets
119+
./scripts/query_config --grids
120+
./scripts/query_config --machines
121+
```
122+
123+
### Model System Tests
124+
125+
These are tests of properties of the model CIME is included in.
126+
System tests inherit from `SystemTestsCommon` base class (`CIME/SystemTests/system_tests_common.py`). Common test types:
127+
- **ERS**: Exact restart test
128+
- **ERT**: Exact restart with different threading
129+
- **SMS**: Smoke test
130+
- **SEQ**: Sequencing test
131+
132+
Each test type has its own module in `CIME/SystemTests/`.
133+
134+
### XML-Based Configuration
135+
136+
CIME is heavily XML-driven. Key concepts:
137+
- Generic XML handling is in `CIME/XML/generic_xml.py`
138+
- All XML classes inherit from `GenericXML`
139+
- XML schemas are in `CIME/data/config/xml_schemas/`
140+
- Config files define machines, compsets, grids, tests
141+
142+
### Case Management Tools
143+
144+
Located in `CIME/Tools/`, these are executable scripts:
145+
- `xmlchange`: Modify case XML variables
146+
- `xmlquery`: Query case XML variables
147+
- `case.setup`: Setup case directory structure
148+
- `case.build`: Build the case
149+
- `case.submit`: Submit case to batch system
150+
- `preview_namelists`: Generate and preview namelists
151+
152+
## Documentation
153+
154+
Build Sphinx documentation:
155+
```bash
156+
cd doc
157+
make clean
158+
make api
159+
make html
160+
```
161+
162+
Requires: `sphinx`, `sphinxcontrib-programoutput`, and custom theme (see `doc/README`).
163+
164+
Online documentation: https://esmci.github.io/cime
165+
166+
## Development Notes
167+
168+
- When modifying Case env classes, changes affect the case's XML files
169+
- The Case class extends across multiple files using imports (see imports at end of `case.py`)
170+
- CIME must be integrated with host models (CESM, E3SM, NorESM) to run Model System Tests
171+
on a supported machine (found using `./scripts/query_config --machines`)/
172+
- Machine-specific configurations are in XML files, not hardcoded
173+
- Git submodules may need initialization: `git submodule update --init`

0 commit comments

Comments
 (0)