Actor SDG Sweep Config

Purpose

Generate reproducible variations of an Isaac Sim Replicator Agent (IRA) YAML configuration. A sweep samples selected configuration fields across multiple variants. Each variant receives a distinct random seed and writer output directory. Optionally run actor_sdg.py on each generated variant via scripts/batch_actor_sdg.py.

Security

Schema validation runs by default. --omit-schema-check writes variants without JSON Schema verification; use only when the caller explicitly accepts unchecked YAML (for example schema unavailable offline). Prefer --dry-run to preview without writing files. Batch execution launches the local actor_sdg.py entry point via subprocess with a fixed argument list (shell=False).

Prerequisites

• Python 3 with PyYAML.
• jsonschema and the IRA config_schema directory for schema validation.
• An existing IRA YAML configuration with the isaacsim.replicator.agent root key.
• A writable output directory, preferably under $WORKSPACE_DIR.
• An Isaac Sim install or source build for optional Actor SDG execution.

Limitations

• The generator changes fields that already exist in the base configuration. It may add the standard root seed field when the base omits it.
• Schema validation cannot run without jsonschema and the matching schema from the installed IRA extension.
• Config generation is deterministic. Actor SDG execution is not idempotent and can replace dataset outputs.
• The batch runner executes variants sequentially. It does not schedule work across machines or GPUs.

Available Scripts

Script	Purpose	Arguments
scripts/config_variation_generator.py	Generate validated config variants and manifest.csv.	CLI flags through argparse; run with --help for details.
scripts/batch_actor_sdg.py	Preview or run actor_sdg.py for generated variants.	CLI flags through argparse; run with --help for details.

Running scripts

From agent runtimes that expose skill execution helpers, invoke a script with run_script():

run_script(
    "scripts/config_variation_generator.py",
    args=[
        "--base", "base.yaml",
        "--sweep", "sweep.yaml",
        "--output", "variants",
        "--dry-run",
    ],
)

From the repository root, run the generator with Python:

python3 skills/actor-sdg-sweep-config/scripts/config_variation_generator.py \
  --base base.yaml \
  --sweep sweep.yaml \
  --output "$WORKSPACE_DIR/actor_sdg_variants" \
  --dry-run

Sweep specification

The sweep file contains a positive count and a parameters list:

count: 12
parameters:
  - path: isaacsim.replicator.agent.character.groups.workers.num
    type: choice
    values: [5, 10, 20]
  - path: isaacsim.replicator.agent.simulation_duration
    type: fixed
    value: 30

Supported sampling types are:

Type	Required value
choice	A non-empty values list.
uniform	An ordered numeric range.
random_int	An ordered integer range.
linspace	An ordered numeric range.
fixed	A value.

Workflow

1. Validate the inputs

1. Resolve the base configuration and sweep file.
2. Parse both files as YAML mappings.
3. Require the isaacsim.replicator.agent root key.
4. Confirm that every dotted sweep path exists in the base configuration, except the standard root seed.
5. Confirm the count and sampling values are valid.

2. Preview the sweep

Run the generator with --dry-run:

python3 skills/actor-sdg-sweep-config/scripts/config_variation_generator.py \
  --base base.yaml \
  --sweep sweep.yaml \
  --output "$WORKSPACE_DIR/actor_sdg_variants" \
  --seed 42 \
  --dry-run

Report the count, parameter paths, sampling types, seed, schema location, and output directory. The generator refuses to replace existing variant directories by default. Pass --overwrite only after the user approves replacement.

3. Generate the configurations

Remove --dry-run after the preview is correct:

python3 skills/actor-sdg-sweep-config/scripts/config_variation_generator.py \
  --base base.yaml \
  --sweep sweep.yaml \
  --output "$WORKSPACE_DIR/actor_sdg_variants" \
  --seed 42

Use --schema-dir when automatic schema discovery cannot find the installed IRA schema. Do not use --omit-schema-check unless the user accepts unvalidated output.

4. Verify the configurations

1. Confirm the command exits with code 0.
2. Confirm the number of variant_*/config.yaml files matches the requested count.
3. Read manifest.csv and one generated configuration.
4. Report whether schema validation passed, was skipped, or was unavailable.
5. Do not call the configurations valid when schema validation did not run.

5. Preview optional data generation

Use the batch runner in dry-run mode:

python3 skills/actor-sdg-sweep-config/scripts/batch_actor_sdg.py \
  --variants "$WORKSPACE_DIR/actor_sdg_variants" \
  --python-sh "$ISAAC_SIM_DIR/python.sh" \
  --actor-sdg "$ISAAC_SIM_DIR/tools/actor_sdg/actor_sdg.py" \
  --dry-run

Before removing --dry-run, report the selected configurations, output locations, and expected runtime. Actor SDG execution can replace generated data, so run it only after the user approves the batch.

6. Report the result

Report the base configuration, sweep file, output directory, count, seed, manifest path, validation status, and any failed variant IDs. After data generation, read run_results.csv and report each failed variant.

Troubleshooting

Error or symptom	Cause	Solution
Sweep path does not exist	The dotted path is absent from the base configuration.	Correct the path or add the field to the base configuration first.
Schema validation unavailable	jsonschema or the matching IRA schema is missing.	Install jsonschema and pass --schema-dir.
Output variants already exist	The generator protects existing files.	Inspect the variants, then rerun with --overwrite after approval.
actor_sdg.py not found	The install or source path was not detected.	Pass the exact path through --actor-sdg.
A batch variant fails	Actor SDG returned a nonzero exit code or timed out.	Inspect its log and the matching row in run_results.csv.