Proportional + Integral (PI)

This information applies to the

CompactLogix

5370,

ControlLogix

5570,

Compact GuardLogix

5370,

GuardLogix

5570,

CompactLogix

5380,

CompactLogix

5480, and

ControlLogix

5580 controllers.

The PI instruction provides two methods of operation. The first method follows the conventional PI algorithm in that the proportional and integral gains remain constant over the range of the input signal (error). The second method uses a non-linear algorithm where the proportional and integral gains vary over the range of the input signal. The input signal is the deviation between the setpoint and feedback of the process.

Available Languages

Ladder Diagram

This instruction is not available in ladder diagram.

Function Block

Structured Text

PI(PI_tag);

Operands

Function Block

Operand	Type	Format	Description
PI tag	PROP_INT	structure	PI structure

Structured Text

Operand	Type	Format	Description
PI tag	PROP_INT	structure	PI structure

See Structured Text Syntax
for more information on the syntax of expressions within structured text.

PROP_INT Structure

Input Parameter	Data Type	Description
EnableIn	BOOL	Enable input. If cleared, the instruction does not execute and outputs are not updated. Default is set.
In	REAL	The process error signal input. This is the difference between setpoint and feedback. Valid = any float Default = 0.0
Initialize	BOOL	The instruction initialization command. When set, Out and internal integrator are set equal to the value of InitialValue. Default is cleared.
InitialValue	REAL	The initial value input. When Initialize is set, Out and integrator are set to the value of InitialValue. The value of InitialValue is limited using HighLimit and LowLimit. Valid = any float Default = 0
Kp	REAL	The proportional gain. This affects the calculated value for both the proportional and integral control algorithms. If invalid, the instruction clamps Kp at the limits and sets the appropriate bit in Status. Valid = any float > 0.0 Default = minimum positive float
Wld	REAL	The lead frequency in radians/second. This affects the calculated value of the integral control algorithm. If invalid, the instruction clamps Wld at the limits and sets the appropriate bit in Status. Valid = see the Description section below for valid ranges Default = 0.0
HighLimit	REAL	The high limit value. This is the maximum value for Out. If HighLimit LowLimit, the instruction sets HighAlarm and LowAlarm, sets the appropriate bit in Status, and sets Out = LowLimit. Valid = LowLimit < HighLimit maximum positive float Default = maximum positive float
LowLimit	REAL	The low limit value. This is the minimum value for Out. If HighLimit LowLimit, the instruction sets HighAlarm and LowAlarm, sets the appropriate bit in Status, and sets Out = LowLimit. Valid = maximum negative float LowLimit < HighLimit Default = maximum negative float
HoldHigh	BOOL	The hold high command. When set, the value of the internal integrator is not allowed to increase in value. Default is cleared.
HoldLow	BOOL	The hold low command. When set, the value of the internal integrator is not allowed to decrease in value. Default is cleared.
ShapeKpPlus	REAL	The positive Kp shaping gain multiplier. Used when In is 0. If invalid, the instruction clamps ShapeKpPlus at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = 0.1 to 10.0 Default = 1.0
ShapeKpMinus	REAL	The negative Kp shaping gain multiplier. Used when In is < 0. If invalid, the instruction clamps ShapeKpMinus at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = 0.1 to 10.0 Default = 1.0
KpInRange	REAL	The proportional gain shaping range. Defines the range of In (error) over which the proportional gain increases or decreases as a function of the ratio of \| In \| / KpInRange. When \| In \| > KpInRange, the instruction calculates the change in proportional error using entered the Kp shaping gain x (In - KpInRange). If invalid, the instruction clamps KpInRange at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = any float > 0.0 Default = maximum positive float
ShapeWldPlus	REAL	The positive Wld shaping gain multiplier. Used when In is 0. If invalid, the instruction clamps ShapeWldPlus at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = 0.0 to 10.0 Default = 1.0
ShapeWldMinus	REAL	The negative Wld shaping gain multiplier. Used when In is < 0. If invalid, the instruction clamps ShapeWldMinus at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = 0.0 to 10.0 Default = 1.0
WldInRange	REAL	The integral gain shaping range. Defines the range of In (error) over which integral gain increases or decreases as a function of the ratio of \| In \| / WldInRange. When \|In\| > WldInRange, the instruction limits In to WldInRange when calculating integral error. If invalid, the instruction clamps WldInRange at the limits and sets the appropriate bit in Status. Not used when NonLinearMode is cleared. Valid = any float > 0.0 Default = maximum positive float
NonLinearMode	BOOL	Enable the non-linear gain mode. When set, the instruction uses the non-linear gain mode selected by ParabolicLinear to compute the actual proportional and integral gains. When cleared, the instruction disables the non-linear gain mode and uses the Kp and Wld values as the proportional and integral gains. Default is cleared.
ParabolicLinear	BOOL	Selects the non-linear gain mode. The modes are linear or parabolic. When set, the instruction uses the parabolic gain method of y=a * x²+ b to calculate the actual proportional and integral gains. If cleared, the instruction uses the linear gain method of y=a * x + b. Default is cleared.
TimingMode	DINT	Selects timing execution mode. 0 = Periodic mode 1 = Oversample mode 2 = Real time sampling mode For more information about timing modes, see Function Block Attributes. Valid = 0 to 2 Default = 0
OversampleDT	REAL	Execution time for oversample mode. Valid = 0 to 4194.303 seconds Default = 0
RTSTime	DINT	Module update period for real time sampling mode Valid = 1 to 32,767ms Default = 1
RTSTimeStamp	DINT	Module time stamp value for real time sampling mode. Valid = 0 to 32,767ms Default = 0

Output Parameter	Data Type	Description
EnableOut	BOOL	Indicates the execution status of the instruction.
Out	REAL	The calculated output of the PI algorithm. Math status flags are set for this output.
HighAlarm	BOOL	The maximum limit alarm indicator. Set when the calculated value for Out HighLimit and the output and integrator are clamped at HighLimit.
LowAlarm	BOOL	The minimum limit alarm indicator. Set when the calculated value for Out LowLimit and output and integrator are clamped at LowLimit.
DeltaT	REAL	Elapsed time between updates. This is the elapsed time in seconds used by the control algorithm to calculate the process output.
Status	DINT	Status of the function block.
InstructFault (Status.0)	BOOL	The instruction detected one of the following execution errors. This is not a minor or major controller error. Check the remaining status bits to determine what occurred.
KpInv (Status.1)	BOOL	Kp < minimum or Kp > maximum.
WldInv (Status.2)	BOOL	Wld < minimum or Wld > maximum.
HighLowLimsInv (Status.3)	BOOL	HighLimit LowLimit.
ShapeKpPlusInv (Status.4)	BOOL	ShapeKpPlus < minimum or ShapeKpPlus > maximum.
ShapeKpMinusInv (Status.5)	BOOL	ShapeKpMinus < minimum or ShapeKpMinus > maximum.
KpInRangeInv (Status.6)	BOOL	KpInRange < minimum or KpInRange > maximum.
ShapeWldPlusInv (Status.7)	BOOL	ShapeWldPlus < minimum or ShapeWldPlus > maximum.
ShapeWldMinusInv (Status.8)	BOOL	ShapeWldMinus < minimum or ShapeWldMinus > maximum.
WldInRangeInv (Status.9)	BOOL	WldInRange < minimum or WldInRange > maximum.
TimingModeInv (Status.27)	BOOL	Invalid TimingMode. For more information about timing modes, see Function Block Attributes.
RTSMissed (Status.28)	BOOL	Only used in real time sampling mode. Set when ABS \| DeltaT - RTSTime \| > 1 (.001 second).
RTSTimeInv (Status.29)	BOOL	Invalid RTSTime value.
RTSTimeStampInv (Status.30)	BOOL	Invalid RTSTimeStamp value.
DeltaT (Status.31)	BOOL	Invalid DeltaT value.

Description

The PI instruction uses the position form of the PI algorithm. This means the gain terms are applied directly to the input signal, rather than to the change in the input signal. The PI instruction is designed to execute in a task where the scan rate remains constant.

In the non-linear algorithm, the proportional and integral gains vary as the magnitude of the input signal changes. The PI instruction supports two non-linear gain modes: linear and parabolic. In the linear algorithm, the gains vary linearly as the magnitude of input changes. In the parabolic algorithm, the gains vary according to a parabolic curve as the magnitude of input changes.

The PI instruction calculates Out using this equation:

Whenever the value computed for the output is invalid, NAN, or Plus or Minus sign

INF, the instruction sets Out = the invalid value and sets the math overflow status flag. The internal parameters are not updated. In each subsequent scan, the output is computed using the internal parameters from the last scan when the output was valid.

Operating in Linear Mode

In linear mode, the non-linear gain mode is disabled. The Kp and Wld values are the proportional and integral gains used by the instruction. The instruction calculates the value for Out using these equations:

Value	Equation
ITerm	where DeltaT is in seconds
PTerm	Kp x In
Out	ITerm + PTerm

with these limits on Wld:

Low Limit > 0.0

High Limit = 0.7

/DeltaT

WldInput = In

Operating in Non-Linear Mode

In non-linear mode, the instruction uses the non-linear gain mode selected by ParabolicLinear to compute the actual proportional and integral gains.

The gains specified by Kp and Wld are multiplied by 1.0 when In = 0. Separate proportional and integral algorithms increase or decrease the proportional or integral gain as the magnitude of error changes. These algorithms use the input range and shaping gain parameters to compute the actual proportional and integral gains. Input range defines the range of In (i.e. error) over which the gain is shaped. Input ranges are set by the two KpInRange and WldInRange. Shaping gain defines the gain multiplier for the quadrant controlled by the shaping gain parameter. Shaping gains are set by ShapeKpPlus, ShapeKpMinus, ShapeWldPlus and ShapeWldMinus.

The ParabolicLinear input selects the non-linear gain mode. If ParabolicLinear is cleared, linear mode is selected. If ParabolicLinear is set, parabolic mode is selected.

To configure a particular shaping gain curve, enter a shaping gain 0.0-10.0 for integral shaping, a shaping gain 0.1-10.0 for proportional shaping, and the input range over which shaping is to be applied. Kp and Wld are multiplied by the calculated ShapeMultiplier to obtain the actual proportional and integral gains. Entering a shaping gain of 1.0 disables the non-linear algorithm that calculates the proportional or integral gain for the quadrant.

When the magnitude of In (error) is greater then InRange then the ShapeMultiplier equals the value computed when | In | was equal to InRange.

The following diagram illustrates the maximum and minimum gain curves that represent the parabolic and linear gain equations.

The instruction calculates the value for Out using these equations:

Value	Equation
Kp shaping gain multiplier
Kp input ratio
Kp ratio
Kps shaping gain
Proportional output
Wld shaping gain
Wld input
Wld input ratio
Wld ratio
Wlds shaping gain
Wlds limits
Integral output
Output

Limiting

The instruction stops the ITerm windup based on the state of the hold inputs.

Condition	Action

The instruction also stops integrator windup based on the HighLimit and LowLimit values.

Condition	Action
Integrator > HighLimit	Integrator = HighLimit
Integrator > LowLimit	Integrator = LowLimit

The instructions limits the value of Out based on the HighLimit and LowLimit values.

Condition	Action
HighLimit LowLimit	Out = LowLimit ITerm = LowLimit HighLowLimsInv is set HighAlarm is set LowAlarm is set WldInput = 0
Out HighLimit	Out = HighLimit ITerm = ITerm _n-1 HighAlarm is set
ITerm > HighLimit	ITerm = HighLimit
Out LowLimit	Out = LowLimit ITerm = ITerm _n-1 LowAlarm is set
ITerm < LowLimit	ITerm = LowLimit

Affects Math Status Flags

Major/Minor Faults

None specific to this instruction. See Common Attributes for operand-related faults.

Execution

Function Block

Condition	Action Taken
Prescan	EnableIn and EnableOut are cleared to false.
Tag.EnableIn is false	EnableIn and EnableOut bits are cleared to false.
Tag.EnableIn is true	EnableIn and EnableOut bit is set to true. The instruction executes.
Instruction first run	Out n-1 = 0 The algorithm used to calculate Out will not be executed.
Instruction first scan	Out n-1 = 0 The algorithm used to calculate Out will not be executed.
Postscan	EnableIn and EnableOut bits are cleared to false.

Structured Text

Condition/State	Action Taken
Prescan	See Prescan in the Function Block table.
Normal Execution	See Tag.EnableIn is true in the Function Block table.
Postscan	See Postscan in the Function Block table.

Example

The PI instruction is a regulating instruction with proportional and integral gain components. The integral gain component is set by the user in radians/sec; this sets the basic frequency response of the PI regulator. The proportional gain sets the overall gain of the block, including the proportional AND integral gain of the block.

Excluding initialization and holding/clamping functionality, the following diagram shows the PI block’s basic regulating loop while in the linear mode.

PI Instruction: Linear Mode

The following example shows the PI instruction used as a velocity regulator. In this example, velocity error is created by subtracting the velocity feedback signal (see the PMUL instruction example) from the system’s velocity reference (through the SCRV instruction). Velocity error is driven directly into the PI instruction, which acts on this signal according to the function shown in the diagram above.

Function Block

Structured Text

Reference_Select.In1 := Master_Machine_Ref;

Reference_Select.Select1 := Master_Machine_Select;

Reference_Select.In2 := Section_Jog;

Reference_Select.Select2 := Jog_Select;

SSUM(Reference_Select);

S_Curve.In := Reference_Select.Out;

S_Curve.AccelRate := accel_rate;

S_Curve.DecelRate := accel_rate;

SCRV(S_Curve);

PMUL_01.In := Resolver_Feedback;

PMUL_01.WordSize := 12;

PMUL_01.Multiplier := 100000;

PMUL(PMUL_01);

Speed_Feedback := PMUL_01.Out;

Velocity_Error := S_Curve.Out - Speed_Feedback;

PI_01.In := Velocity_Error;

PI_01.Initialize := Enable_Regulator;

PI_01.Kp := Velocity_Proportional_Gain;

PI_01.Wld := Velocity_Integral_Gain;

PI(PI_01);

Torque_Reference := PI_01.Out;

Drives Instructions

Provide Feedback

Have questions or feedback about this documentation? Please submit your feedback here.