ctrl_specs_new

Purpose:

Specify user loop configuration via keywords

Enter:

ctrl_specs_new [control_spec_file]

Where:

control_spec_file Specify the filename containing the user loop specifications via keywords.

Example:

         See Notes.

Notes:

A new way to specify user control loops is now available in CyFlex. Each user loop may be specified in a unique file and the specifications are entered via keywords. If a particular specification is not needed, then its associated keyword should not be entered. When a specification is not entered the controller will assume default values. A minimum of 4 keywords and the associated specification must be entered for each controller.

The following describes the available controller keywords, the specifications that must follow each keyword, whether or not the keyword is required, and any associated default values. Following the description is an example specification for a user control loop.

     Specify the label and computation rate for the controller
(REQUIRED ENTRY)

@USER_LOOP_CTRLER
<label_root>   <command_output_units>  <interval>  <open_loop_ramp_rate>

where:
label root – The root of the variables created for the controller.
The labels created are:
label_root_CM    (ctrler command output)
label_root_OL    (ctrler open loop target)
label_root_PT    (ctrler proportional term)
label_root_IT    (ctrler integral term)
label_root_DT    (ctrler derivative term)
label_root_FF    (ctrler feed forward term)
label_root_FA    (ctrler feed forward active)
label_root_RF    (Reference of feedback variable)
label_root_TR    (Target of feedback variable)
label_root_ER    (Error of feedback variable)
label_root_TL    (Error is in tolerance LOGICAL VARIABLE)
label_root_IN    (Name of ERROR IS IN TOLERANCE event)
label_root_OT    (Name of ERROR IS OUT OF TOLERANCE event)

NOTE: Since 3 characters are appended to the label root,
the root should have a maximum of 12 characters.

command   – the units assigned to created variables
output      NOTE: The units of the feedback variable are assigned
units             to _RF, _TR, & _ER variables.

interval  $-$ The calculation interval for the control loop. Valid
entries are SLO, MED, and FAS.

open loop – The open loop ramp rate value.
ramp rate

Specify the feedback variable for the controller
(REQUIRED ENTRY)

@CTRLER_FEEDBACK_VRBL
<label>     <closed_loop_ramp_rate>    <error_term_tolerance>

where:
label       – The label of the parameter being controlled by the
control loop.

closed loop – The closed loop ramp rate value.
ramp rate

error term  – The maximum value of the error term for the control
tolerance     to be within tolerance. When the error is less than
value the label ‘label_root_TL’ will be TRUE, otherwise it will be FALSE.

Specify the PID gains for the controller
(REQUIRED ENTRY)

@CTRLER_GAINS
<proportional>    <integral>     <derivative>

where:
proportional – The proprotional gain value

integral          – The integral gain value

derivative      – The derivative gain value

Specify the output channel for the controller
(REQUIRED ENTRY)

@CTRLER_OUTPUT_CHAN

One of 4 output types may be specified, AO, CO, DO, or RV

AO  <channel> <zero_value> <span_value> <filter_constant>

where:
channel        – is the analog output channel number that
will receive the _CM value.

zero_value    – the command output value associated with
0 % of the range of the AO device.

span_value    – the commnd output value associated with
100 % of the range of the AO device.

filter_constant – a recursive filter factor between 0 and 1.0

CO  <channel> <zero_value> <span_value> <filter_constant>

where:
channel        – is the counter output channel number that
will receive the _CM value.

zero_value     – the command output value associated with
0 % of the range of the CO device.

span_value     – the commnd output value associated with
100 % of the range of the CO device.

filter_constant – a recursive filter factor between 0 and 1.0

RV  <target_label>  <bias>  <gain>   <filter>

where:
target_label   – is the real variable where the
_CM value will be placed

bias           – an offset applied to the value before
units conversion

gain           – a multiplier applied to the value
before units conversion

filter         – a recursive filter factor between 0 and 1.0

DO  <DO PWM label>  <base_period> [enable_label]

where:

DO_PWM_label $-$ is the label of the DO bit that will
provide the PWM output. This label
must already exist and be contained in
the do_specs file.

base_period  $-$ A label whose value will be used as the
base period of the PWM output. A numeric
value may be specified. For this case, the
value must also contain the time units,
eg. 30[sec].

enable_label $-$ The label of a LOGICAL_VARAIBLE that
is used to disable/enable the PWM
output.

Specify some attributes of the created controller variables.
(OPTIONAL ENTRIES)

@USER_LOOP_VRBL_OPTS_TR
<display_precision>     <history_active>     <history_tolerance>

where:
display   $-$ The number of decimal places to be displayed by
precision   the display task when the variable
is displayed. Default is 1

history   $-$ A flag indicating if the variable should be included
active      in the history log. Valid entries for this field
are YES or NO. Default is NO.

history   $-$ The amount the variable must change for it to be
tolerance   written to the history log. Default is 5.0

NOTE:  There is a similar specification for each of the created variables.
The only thing that is different is the suffix of the keyword. The
additional keywords for created variable options are:

@USER_LOOP_VRBL_OPTS_RF
@USER_LOOP_VRBL_OPTS_ER
@USER_LOOP_VRBL_OPTS_CM
@USER_LOOP_VRBL_OPTS_PT
@USER_LOOP_VRBL_OPTS_IT
@USER_LOOP_VRBL_OPTS_DT
@USER_LOOP_VRBL_OPTS_FF
@USER_LOOP_VRBL_OPTS_OL

Specify an attribute of the created controller LOGICAL variables.
(OPTIONAL ENTRIES)

@USER_LOOP_VRBL_OPTS_TL
<history_active>

where:
history  $-$ A flag indicating if the LOGICAL_VARIABLE should be included
active in the history log. Valid entries for this field are YES or NO. Default is NO.

NOTE:  There is a similar specification for each of the created LOGICAL
variables. The only thing that is different is the suffix of the
keyword. The additional keyword for created LOGICAL variable
options are:

@USER_LOOP_VRBL_OPTS_FA

Specify the command output bounds for the controller
(OPTIONAL ENTRY)

@CTRLER_OUTPUT_BOUNDS
<lower_bound>     <upper_bound>

where:
lower bound $-$ This entry may be a value of the lower bound for the
output term or it may be a label of a varaible. If
it is a variable label, its value is used as the lower
bound. The default lower bound is 0.

upper bound $-$ This entry may be a value of the upper bound for the
output term or it may be a label of a varaible. If
it is a variable label, its value is used as the upper
bound. The default lower bound is 100.

Specify the integral term bounds for the controller
(OPTIONAL ENTRY)

@CTRLER_INTEGRAL_BOUND_LABELS
<lower_bound_label>     <upper_bound_label>

where:
lower bound label $-$ The label of the variable containing the value
of the lower bound for the integral term. If no
lower bound variable is specified an entry of
$null should be provided when an upper bound
label is specified.

upper bound label $-$ The label of the variable containing the value
of the upper bound for the integral term. If no
upper bound variable is specified an entry of
$null should be provided when an upper bound
label is specified.

NOTE: If the @CTRLER_INTEGRAL_BOUND_LABELS is not
entered, then no integral bounds will be applied.

Specify the hystersis for the controller
(OPTIONAL ENTRY)

@CTRLER_HYSTERSIS
<value>

where:
value $-$ is the hystersis value for the controlled device. If not specified, a value of 0.0 will be assumed.

Specify the command map pathname for the controller
(OPTIONAL ENTRY)

@CTRLER_COMMAND_MAP_FILE
<pathname>

where:
pathname $-$ is the full path name of the file to used as a command map for the output command.  If this key word is not
entered, then no command map will be applied to the output command.

Specify the error scaling variable for the controller
(OPTIONAL ENTRY)

@CTRLER_ERROR_SCALING_LABEL
<scale_error_label>

where:
scale_error $-$ The label whose value will be used to scale the computed
label error term.  The computed error is multiplied by this value before the output term is computed.  If
this keyword is not entered no scaling will be performed.

Specify the feed forward variable for the controller
(OPTIONAL ENTRY)

@CTRLER_FEED_FORWARD
<label>     <active>    <gain>

where:
label    $-$ A label of an CyFlex variable is entered. Its value
is the gain that will be used.

active   $-$ A flag indicating if the feed forward term is initially
active or inactive. Valid entries for this field are
YES or NO.

gain     $-$ The feed forward gain that will be used when feed forward
is active.

NOTE: If this keyword is not entered, then no feed forward
term will be computed.

Specify the local command label for the controller
(OPTIONAL ENTRY)

@CTRLER_LOCAL_COMMAND_LABEL
<local_label>

where:
local_label $-$ is the name of the CyFlex variable that contains
the local command output when the control loop
is not under computer control. If this keyword
is not entered then no local command will be applied.

Specify the remote sense LOGICAL VARIABLE for the controller
(OPTIONAL ENTRY)

@CTRLER_REMOTE_SENSE_LABEL
<remote_label>

where:
remote_label $-$ is the label of the CyFlex LOGICAL_VARIABLE that
will be used to determine if remote (computer)
control is to be used or local control. If this
keyword is not entered, then only remote (computer) control will be used.

Specify the upper and lower bounds of the target for the feed back
variable   (OPTIONAL ENTRY)

@USER_LOOP_TARGET_BOUNDS
<lower bound>   <upper bound>

where:
<lower bound> $-$ 1. The value of the lower bound that should be
place on the target of the controller.
e.g. 34

2. The value of the lower bound, with units specified,
that should be place on the target of the controller.
e.g. 34[deg_f]

3. An CyFlex variable name. If the specified variable
name does not exist, it will be created as a
REAL_VARIABLE and given the units of the feedback
variable.  If the target variable exists it may be
a REAL_VARIABLE or an INTEGER_VARIABLE. The value
of this variable will then be used as the lower
bound of the target.
e.g. Oil_rfl_tar_low_bnd

4. A double quoted expression. The expression will be
evaluated and the result will be used as the lower
bound of the target.
e.g. “Oil_Rf_tar_low_bnd + barometer”

<upper_bound>  $-$ Same as lower bound.

The bounds are independent and any of the above options can be specified
for each bound.

Specify the initial mode and set point for the controller
(OPTIONAL ENTRY)

@INITIAL_CTRLER_STATE
<controller mode>           <setpoint>

where:

<controller mode> $-$ OPEN_LOOP   $-$ The controller will be placed
in the open loop mode when
ctrl_specs is run.

CLOSED_LOOP $-$ The controller will be placed
in the closed loop mode when
ctrl_specs is run.

<setpoint>        $-$ the target value of the specified <mode>.
This entry may be a constant, label, or
computed expression.

Indicate the end of the specifications for a user loop controller

$END Note: Additional user loops may be specified following the $END.

@USER_LOOP_CTRLER
# label       command         interval      open$-$loop
# root      output units                    ramp rate
coolInTLoop        %               SLO            0.0

@CTRLER_FEEDBACK_VRBL
# label     closed loop    error term
#            ramp rate      tolerance
cool_in_t      0.0           1.0

@CTRLER_GAINS
#    proportional      integral      derivative
1.0             .1333         1.125

@CTRLER_OUTPUT_CHAN
#output type      channel   bias       span       filter contstant
AO               2       0.0        400.           0.0

$END

See Also: