How to run an Intervention Work Package

Paid Feature - Only available for some customers

This feature is only available to certain customers. If you are interested in using this feature, please contact Zepben for more information.

This guide covers the practical steps for running an Intervention work package. For a conceptual overview of interventions and how candidates are generated and allocated, see What are Interventions and how do they work?. For the full list of intervention types and their parameters, see Interventions Options.

An intervention work package is not a separate mutation - it is a normal work package (submitted with Mutation.run_work_package and WorkPackageInput, same as in How to run a Work Package) with an additional intervention block set, pointing back at a parentWorkPackageId. The intervention block can combine one candidate intervention with phase rebalancing, DVMS, and/or load reshaping in the same work package - see Stacking Interventions.

Step 1: Run a parent work package

The parent work package is a regular (non-intervention) work package. Candidate-based interventions decide where to intervene using its results, so it must be configured correctly up front:

• Write results to Postgres: set writerType=POSTGRES on the parent work package's writerConfig. Candidate generation queries the parent's results directly from the database, so a parent written with writerType=PARQUET cannot be used - the intervention will find no candidates. This applies to every candidate-based intervention type, not just the asset upgrades.

• Enable enhanced metrics: set populateEnhancedMetrics=True. Candidate generation only reads the network_performance_metrics_enhanced table - no raw tables (energy_meters_raw, energy_meter_voltages_raw, overloads_raw, voltage_exceptions_raw) need to be stored.

• Set Measurement Zones at the transformer level: configure meterPlacementConfig with distTransformers=True (see Meter Placement Config). This is required for candidate-based interventions that use measurement-zone metrics (COMMUNITY_BESS, LV_STATCOMS, DISTRIBUTION_TAP_OPTIMIZATION, DISTRIBUTION_TX_OLTC and VOLTAGE_LINE_UPGRADE). Having a Feeder Head measurement zone is optional, but switch/LV circuit level zones are not supported for any work package feeding a candidate-based intervention. See Measurement Zones.

• Enable asset level summaries if you plan to run an asset upgrade intervention: set assetLevelSummaries on resultProcessorConfig, with thermalLoading=True for THERMAL_LINE_UPGRADE and THERMAL_TRANSFORMER_UPGRADE, and conductorVoltage=True for VOLTAGE_LINE_UPGRADE. Both default to off. These populate asset_level_thermal_loading_summary and asset_level_voltage_summary, which are the only source those three interventions read to find candidates. The other candidate-based types do not need these tables.

  If the summaries are missing, the intervention work package completes successfully having done nothing - it is not treated as an error. Check the summary tables are populated for the parent before concluding there was no work to do.

• Use feederScenarioAllocationStrategy=ADDITIVE (the default). If overridden to RANDOM, the work package will fail to build for any of the seven candidate-based intervention types.

• Keep the year range single or contiguous, not multiple non-contiguous years, for both the base and intervention work packages. For example, {2027} or {2027, 2028, 2029, 2030} are valid, but {2027, 2030} is not supported. This is enforced for the asset upgrade types; for other intervention types there's no build-time check, but non-contiguous years will still produce erroneous results.

Step 2: Keep the intervention work package config aligned with the base

Run the intervention work package with the same configuration as the base, other than the intervention block itself (same load time range, model parameters, network topology fixers, feeders, years, etc.), otherwise you can't tell whether a result difference came from the intervention or from config drift.

Step 3: Configure and submit the intervention work package

Add an intervention block to a WorkPackageInput, pointing parentWorkPackageId at the parent work package from Step 1, and submit it the same way as any other work package.

For a runnable example covering all intervention types, see run_intervention_work_package.py in the hosting-capacity-runner repo.

See Interventions Options for the detail on each intervention type.

Step 4: Monitor and interpret results

Monitoring works the same as any other work package - see How to run a Work Package and How to manage Work Packages.

Expect an intervention work package to take longer than the equivalent non-intervention run over the same feeders and years. The network is modified and re-solved, so the cost is driven by the re-solve rather than by how many interventions are actually applied - a run that applies a handful of upgrades can take about as long as one that applies hundreds. Allow for this when planning study scope and turnaround.

Once complete, the intervention work package produces results in the same output tables as a regular work package, letting you directly compare constraint patterns before and after the intervention. See Output Tables.

Check how many candidates were actually applied

For the candidate-based types, compare the rows in intervention_candidates against the relevant applied table (applied_line_upgrade, applied_transformer_upgrade, and so on) for the work package.

A candidate that cannot be allocated is skipped without an error, so a work package can complete normally while applying far fewer interventions than it identified. For the asset upgrade types this usually means the catalogue had no compatible row - see Asset Upgrade Catalogue Tables. Checking the two counts against each other is the quickest way to tell "the network needed less work than expected" apart from "the intervention could not find anything to install".