🚀 Best Practices for Local & Cluster Runs¶

A workflow you test on your laptop should behave identically on a large compute cluster.
Follow the checklist below to keep every run predictable, resumable, and version‑controlled.

1 Choose the right builder¶

Builder	When to use	Docs
*DesignVariableBuilder *	You have an existing `.aedt` and only need to tweak design variables.	`DesignVariableBuilder`
ModuleBuilder	You want a reusable Python module to generate/modify geometry.	`ModuleBuilder`

(See all builders in the API reference.)

2 Put everything in a `WorkflowConfig`¶

Create or load a WorkflowConfig in Python or YAML.
Include solver options, sweep parameters, simulation list, and cluster resources.
Avoid hard‑coding these values in ad‑hoc Python scripts.

Reserved identifiers: build and prepare — never use them as simulation names.

3 Test locally first¶

intro bash
quansys run config.yaml

A local run confirms the builder works and the sweep hashes create the expected UID folders (000, 001, …).

4 Submit to the cluster¶

intro bash
quansys submit config.yaml my_env --name job_name

submit packages the project, stages input files, and hands the job to the scheduler.

5 Version‑control the artefacts¶

Tip

Commit the config file and the template design (template.aedt) to Git.
With code and configuration under version control, every cluster run can be traced, repeated, and trusted.

YAML round‑trip snippet¶

Need to tweak the workflow in CI without touching Python code?

from quansys.workflow import WorkflowConfig, execute_workflow  

cfg = WorkflowConfig.load_from_yaml("config.yaml")  
cfg.pyaedt_file_parameters.non_graphical = False      # optional tweak  
execute_workflow(cfg)

Use cfg.save_to_yaml("new_config.yaml") to persist edits back to disk.