blockStageChangeCommand

Information

The plant equipment is staged in part based on required capacity, Qrequired, relative to nominal capacity of a given stage, Qstage. This ratio is the operative part load ratio, OPLR.

OPLR = Qrequired / Qstage

If both primary and secondary return temperature and flow rate sensors are available, the sensors in the primary loop are used for calculating Qrequired. (This condition is implemented in Buildings.Templates.Plants.Controls.HeatPumps.AirToWater.)

The required capacity is calculated based on return temperature, active supply temperature setpoint and measured flow through the associated circuit flow meter.

The required capacity used in logic is a rolling average over a period of dtMea of instantaneous values sampled at minimum once every 30 s.

When a stage up or stage down transition is initiated, Qrequired is held fixed at its last value until the longer of the successful completion of the stage change and the duration dtRun.

The nominal capacity of a given stage, Qstage, is calculated as the sum of the design capacities of all units enabled in a given stage.

Staging is executed per the conditions below subject to the following requirements.

• Each stage has a minimum runtime of dtRun. (This condition is implemented in Buildings.Templates.Plants.Controls.Utilities.StageIndex.)
• Timers are reset to zero at the completion of every stage change.
• Any unavailable stage is skipped during staging events, but staging conditionals in the current stage are evaluated as per usual.

A stage up command is triggered if any of the following is true:

• Availability condition: The equipment necessary to operate the current stage is unavailable. The availability condition is not subject to the minimum stage runtime requirement. (This condition is implemented in Buildings.Templates.Plants.Controls.Utilities.StageIndex.)
• Efficiency condition: Current stage OPLR > plrSta for a duration of dtRun.
• Failsafe condition: see Buildings.Templates.Plants.Controls.StagingRotation.FailsafeCondition.

A stage down command is triggered if both of the following are true:

• Next available lower stage OPLR < plrSta for a duration of dtRun.
• The failsafe stage up condition is not true.

Details

A staging matrix staEqu is required as a parameter. See the documentation of Buildings.Templates.Plants.Controls.StagingRotation.EquipmentEnable for the associated definition and requirements.

An "if" condition is used to generate the stage up and down command as opposed to a "when" condition. This means that the command remains true as long as the condition is verified. This is necessary, for example, if no higher stage is available when a stage up command is triggered. Using a "when" condition – which is only valid at the point in time at which the condition becomes true – would prevent the plant from staging when a higher stage becomes available again. To avoid multiple consecutive stage changes, the block that receives the stage up and down command and computes the stage index must enforce a minimum stage runtime of dtRun.

Locking logic for polyvalent heat pump plants

For plants with polyvalent heat pumps (have_php=true), a locking mechanism prevents a race condition in which heating and cooling simultaneously stage up to an infeasible stage combination. Such a combination is encoded as a zero equipment count in the staging matrix. This race condition is not captured by the stage availability logic in Buildings.Templates.Plants.Controls.StagingRotation.StageAvailability: that block evaluates feasibility based on the current stage of the opposite mode, so it correctly clears infeasible stages in steady state, but cannot anticipate that the opposite mode will also stage up within the same event iteration.

The heating-mode instance of this block evaluates the feasibility of the combined next step by looking up the equipment count for the pair (next available higher heating stage, next available higher cooling stage) in the staging matrix. If that count is zero – i.e., the combination is infeasible – the heating block asserts the lock output. This signal is connected to the cooling-mode instance which inhibits the stage-up command. Heating therefore stages up with priority, landing on a combination that is feasible with the current cooling stage.

Parameters

Connectors

Components

Revisions

• July 10, 2026, by Antoine Gautier:
  Refactored to support plants with polyvalent heat pumps.
  This is for #4512.
• May 31, 2024, by Antoine Gautier:
  Refactored using LoadAverage block and added failsafe condition.
• March 29, 2024, by Antoine Gautier:
  First implementation.