Warning, /AID2E-framework/docs/PANDA_YAML_CONFIG.md is written in an unsupported language. File is not indexed.
0001 # PanDAiDDS Scheduler YAML Configuration Guide
0002
0003 This guide explains how to configure the PanDAiDDS scheduler using YAML files in the AID2E framework.
0004
0005 ## Quick Start
0006
0007 ### Minimal Configuration
0008
0009 ```yaml
0010 scheduler:
0011 runner_type: "PanDAiDDSRunner"
0012 parameters:
0013 cloud: "US"
0014 queue: "BNL_PanDA_1"
0015 max_walltime: 3600
0016 core_count: 1
0017 total_memory: 2000
0018 output_location: "./panda_output"
0019 ```
0020
0021 The `name` field will be auto-generated as `user.<username>.aid2e_job`.
0022
0023 ### Full Configuration
0024
0025 ```yaml
0026 scheduler:
0027 runner_type: "PanDAiDDSRunner"
0028 parameters:
0029 name: "user.scientist.experiment" # Must start with 'user.<username>'
0030 cloud: "US"
0031 queue: "BNL_PanDA_1"
0032 source_dir: null # null = current directory
0033 source_dir_parent_level: 1
0034 exclude_source_files:
0035 - "(^|/)\\..*" # Hidden files
0036 - ".*\\.log"
0037 - "__pycache__"
0038 max_walltime: 7200
0039 core_count: 4
0040 total_memory: 8000
0041 enable_separate_log: true
0042 job_dir: "/tmp/panda_jobs"
0043 max_retries: 3
0044 output_location: "./panda_output"
0045 monitor_interval: 120
0046 ```
0047
0048 ## Configuration Fields
0049
0050 ### Required Fields
0051
0052 | Field | Type | Description |
0053 |-------|------|-------------|
0054 | `cloud` | string | PanDA cloud/region (e.g., "US", "EU") |
0055 | `queue` | string | PanDA queue name (e.g., "BNL_PanDA_1") |
0056
0057 ### Optional Fields
0058
0059 | Field | Type | Default | Description |
0060 |-------|------|---------|-------------|
0061 | `name` | string | auto-generated | Job name, must start with `user.<username>` (auto-generates if omitted) |
0062 | `job_name_prefix` | string | "aid2e_job" | Prefix used when auto-generating the PanDA job name |
0063 | `init_env` | string/callable | "source setup_aid2e.sh; bash install_aid2e_dependencies.sh;" | Environment initialization (auto-sets if omitted, prepended if string) |
0064 | `source_dir` | string | project root | Directory to upload to PanDA (auto-sets to project root if omitted) |
0065 | `max_walltime` | int | None | Maximum walltime in seconds |
0066 | `core_count` | int | 1 | CPU cores per job |
0067 | `total_memory` | int | 4000 | Memory in MB per job |
0068 | `enable_separate_log` | bool | true | Enable separate log files |
0069 | `job_dir` | string | None | Job working directory |
0070 | `source_dir_parent_level` | int | 1 | Parent levels to include |
0071 | `exclude_source_files` | list | See below | File patterns to exclude (.venv, venv, .git included) |
0072
0073 ### Default Excluded Files
0074
0075 ```python
0076 [
0077 r"(^|/)\.[^/]+", # Hidden files
0078 "doc*", # Documentation
0079 "DTLZ2*", # Test files
0080 ".*json", # JSON files
0081 ".*log", # Log files
0082 "work", # Work directory
0083 "log", # Log directory
0084 "OUTDIR", # Output directory
0085 "calibrations", # Calibration files
0086 "fieldmaps", # Field maps
0087 "gdml", # GDML geometry
0088 "EICrecon-drich-mobo", # EIC specific
0089 "eic-software", # EIC software
0090 "epic-geom-drich-mobo", # EPIC geometry
0091 "irt", # IRT files
0092 "share", # Shared files
0093 "back*", # Backup files
0094 "__pycache__", # Python cache
0095 ".venv", # Virtual environment
0096 "venv", # Virtual environment
0097 ".git", # Git repository
0098 ]
0099 ```
0100
0101 ## Auto-Generated Fields
0102
0103 ### Name Auto-Generation
0104
0105 The `name` field follows PanDA conventions: `user.<username>.<suffix>`
0106
0107 **Auto-Generation Rules:**
0108 1. **If `name` is omitted or `null`**: Auto-generates from username
0109 2. **System username**: Uses `getpass.getuser()`
0110 3. **Environment override**: Set `PANDA_USERNAME` env var
0111 4. **Validation**: Explicit names must start with `user.`
0112
0113 **Examples:**
0114
0115 ```yaml
0116 # Auto-generate from system username
0117 parameters:
0118 job_name_prefix: "aid2e_job"
0119 cloud: "US"
0120 queue: "BNL_PanDA_1"
0121 # name omitted → "user.<system_username>.aid2e_job"
0122 ```
0123
0124 ```bash
0125 # Override username via environment variable
0126 export PANDA_USERNAME=myuser
0127 # YAML with no name → "user.myuser.aid2e_job"
0128 ```
0129
0130 ```yaml
0131 # Explicit name (must start with 'user.')
0132 parameters:
0133 name: "user.physicist.epic_tracking"
0134 cloud: "US"
0135 queue: "BNL_PanDA_1"
0136 ```
0137
0138 ### Source Directory Auto-Setting
0139
0140 The `source_dir` field specifies which directory to upload to PanDA.
0141
0142 **Auto-Setting Rules:**
0143 1. **If `source_dir` is omitted or `null`**:
0144 - Defaults to the project root directory (calculated from the config module location)
0145 2. **Environment override**: Set `PANDA_SOURCE_DIR` env var
0146 3. **Explicit value**: Provide path directly in config
0147
0148 **Examples:**
0149
0150 ```yaml
0151 # Auto-set to project root directory
0152 parameters:
0153 cloud: "US"
0154 queue: "BNL_PanDA_1"
0155 # source_dir omitted → project root directory
0156 ```
0157
0158 ```bash
0159 # Override via environment variable
0160 export PANDA_SOURCE_DIR=/path/to/source
0161 # YAML with no source_dir → "/path/to/source"
0162 ```
0163
0164 ```yaml
0165 # Explicit source directory
0166 parameters:
0167 source_dir: "/explicit/path/to/upload"
0168 cloud: "US"
0169 queue: "BNL_PanDA_1"
0170 ```
0171
0172 ### Environment Initialization Auto-Setting
0173
0174 The `init_env` field specifies commands to run before job execution.
0175
0176 **Auto-Setting Rules:**
0177 1. **If `init_env` is omitted or `null`**:
0178 - Defaults to `"source setup_aid2e.sh; bash install_aid2e_dependencies.sh;"` to set up the AID2E environment
0179 2. **If `init_env` is provided as a string**:
0180 - Prepends `"source setup_aid2e.sh && bash install_aid2e_dependencies.sh && "` to the provided command
0181 - This ensures the environment is always set up before custom commands
0182 3. **If `init_env` is a callable or other type**:
0183 - Leaves it as-is (no modification)
0184
0185 **Examples:**
0186
0187 ```yaml
0188 # Auto-set to source setup script
0189 parameters:
0190 cloud: "US"
0191 queue: "BNL_PanDA_1"
0192 # init_env omitted → "source setup_aid2e.sh; bash install_aid2e_dependencies.sh;"
0193 ```
0194
0195 ```yaml
0196 # Custom initialization command (setup script will be prepended)
0197 parameters:
0198 init_env: "export MY_VAR=value && module load gcc"
0199 cloud: "US"
0200 queue: "BNL_PanDA_1"
0201 # Result: "source setup_aid2e.sh && bash install_aid2e_dependencies.sh && export MY_VAR=value && module load gcc"
0202 ```
0203
0204 ## Loading Configurations
0205
0206 ### Method 1: Full Config (Recommended)
0207
0208 ```python
0209 from aid2e.utilities.configurations.full_config import load_config
0210
0211 # Load complete configuration
0212 config = load_config("config.yml")
0213
0214 # Access scheduler config
0215 scheduler_config = config.scheduler
0216 panda_config = scheduler_config.parse_runner_params()
0217
0218 print(panda_config.name)
0219 print(panda_config.cloud)
0220 ```
0221
0222 ### Method 2: Scheduler Config Only
0223
0224 ```python
0225 import yaml
0226 from aid2e.utilities.configurations.scheduler_config import SchedulerConfiguration
0227
0228 # Load YAML
0229 with open("scheduler.yml") as f:
0230 data = yaml.safe_load(f)
0231
0232 # Parse
0233 scheduler_config = SchedulerConfiguration(**data)
0234 panda_config = scheduler_config.parse_runner_params()
0235 ```
0236
0237 ### Method 3: Direct PanDA Config
0238
0239 ```python
0240 import yaml
0241 from aid2e.schedulers.PanDAiDDS.config import PanDAiDDSRunnerConfig
0242
0243 # Load YAML (just PanDA parameters)
0244 with open("panda.yml") as f:
0245 data = yaml.safe_load(f)
0246
0247 # Parse
0248 panda_config = PanDAiDDSRunnerConfig(**data)
0249 ```
0250
0251 ## Complete Example
0252
0253 See [`examples/panda_scheduler_config.yml`](panda_scheduler_config.yml) for complete examples including:
0254 - Minimal configuration
0255 - Full configuration with all fields
0256 - Environment variable usage
0257 - Integration with optimizer and problem configs
0258
0259 See [`examples/panda_yaml_loading_example.py`](panda_yaml_loading_example.py) for Python code examples.
0260
0261 ## PanDA Queues
0262
0263 Common PanDA queues:
0264
0265 - `BNL_PanDA_1` - Brookhaven National Laboratory
0266 - `ORNL_Frontier` - Oak Ridge National Laboratory
0267 - `NERSC_Perlmutter` - NERSC Perlmutter supercomputer
0268
0269 Contact your PanDA administrator for available queues in your cloud.
0270
0271 ## Validation
0272
0273 The configuration is validated via Pydantic models:
0274 - Type checking
0275 - Field validation
0276 - Name format validation (must start with `user.`)
0277 - Required field checks
0278
0279 Invalid configurations will raise `ValidationError` with detailed messages.
0280
0281 ## See Also
0282
0283 - [PanDA Documentation](https://panda-wms.readthedocs.io/)
0284 - [iDDS Documentation](https://idds.readthedocs.io/)
0285 - [AID2E Documentation](https://aid2e.github.io/AID2E-framework)
