TARGET
The purpose of TARGET MathVariable is to allow configurors using a simple syntax to implement iterative solve routine. The TARGET type should be used in a multi-step fashion where an initial target object is created then is manipulated in several ways to produce the desired result. The following sections describe the various operations needed to support the TARGET type.
Target Object Creation and Initialization
To create and initialize a Target object, the CREATE operation is used. This creates a new Target object accessible through the variable (example named, TargetA). The attributes set the given property values on the target object. For missing values, default values are used. The exception to this rule is for INITIALTRIALAMOUNT which must be present. If not, an exception will be thrown.
OPERATION="CREATE" | |||
---|---|---|---|
Attribute | Description | Variable? | Default |
MAXTRIALS |
Maximum number of iterations to run before ending the calculation. |
Yes |
50 |
MAXTRIALAMOUNT |
Largest trial value used during the solve. |
Yes |
0 |
MINTRIALAMOUNT | Smallest trial value used during the solve. | Yes | 0 |
TRIALTOLERANCE | The iterations will end when the difference between the desired result and the calculated result is less than this value. | Yes | 0.001 |
PRECISION | The precision to use when rounding. | Yes | 0.001 |
MOREISMORE | Its value determines what happens to the trial result when the trial amount increases. If “Yes” the trial result increases, otherwise it decreases. | No | Yes |
ROUNDTRIALS | If = “Yes”, the trial amounts are rounded at each iteration. | No | No |
INITIALTRIALAMOUNT | The initial trial amount. | Yes | N/A |
XML Schema
<MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="CREATE" MAXTRIALS="50" MAXTRIALAMOUNT="Max" MINTRIALAMOUNT="Min" TRIALTOLERANCE="Tolerance" PRECISION="0.01" MOREISMORE="Yes" ROUNDTRIALS="Yes" INITIALTRIALAMOUNT=" InitTrialAmount"> <Hurdle HURDLENAME="HurdleA" HURDLETYPE="NUMERIC" TOLERANCE="Tolerance"> HurdleValueA </Hurdle> <Hurdle HURDLENAME="HurdleB" HURDLETYPE="NUMERIC" TOLERANCE="Tolerance"> HurdleValueB </Hurdle> </MathVariable> |
XML Example
<MathVariable VARIABLENAME="Target" TYPE="TARGET" OPERATION="CREATE" MAXTRIALS="MaxTrials" MAXTRIALAMOUNT="FaceAmount" MINTRIALAMOUNT="InitialPolicyMIP" TRIALTOLERANCE="0.001" PRECISION="0.01" MOREISMORE="Yes" ROUNDTRIALS="Yes">InitTrialAmount</MathVariable> |
Adding Hurdles
Hurdles are the goals that are to be achieved. There may be multiple hurdles with each being one of two types: numeric or boolean. A Target object keeps its hurdles in a Map, so each one must have a unique name.
Adding hurdles to a target is accomplished as subsequent operations on the object created by the TARGET CREATE operation as shown in the example above.
OPERATION="ADDHURDLE" | ||
Attribute | Description | Required? |
HURDLENAME | Name of the hurdle. Must be unique within the target variable. | Yes |
HURDLETYPE | Either NUMERIC or BOOLEAN | Yes |
TOLERANCE | How close the target amount needs to be to the hurdle value. | No. Default = 0. |
Text value | The value against which the target values are being matched | Yes |
XML Example
<MathVariable VARIABLENAME="Target" TYPE="TARGET" OPERATION="ADDHURDLE" HURDLENAME="NumericHurdle" HURDLETYPE="NUMERIC" TOLERANCE="TargetingHurdleTolerance">TargetAVOverride</MathVariable> <MathVariable VARIABLENAME="Target" TYPE="TARGET" OPERATION="ADDHURDLE" HURDLENAME="BooleanHurdle" HURDLETYPE="BOOLEAN">1</MathVariable> |
Setting Hurdles’ to Current Result
At the end of each trial, SETRESULT operation can be used to specify the Target object about the value obtained for each hurdle during the current trial.
OPERATION="SETRESULT" |
<MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="SETRESULT" HURDLENAME="HurdleA">CurrentTrialResult</MathVariable> Example <MathVariable VARIABLENAME="Target" TYPE="TARGET" OPERATION="SETRESULT" HURDLENAME="BooleanHurdle">0</MathVariable> |
Note: An exception will be thrown if there is no hurdle with the specified HURDLENAME.
Running the Target Routine
At the end of each trial (after setting hurdle results), the target routine should be executed so that the target object can choose the next trial amount based on the results. This is done through the COMPUTE operation. Also, the Target object can be set to reject the current trial result and, in addition, can set the new Minimum or Maximum, regardless of the MoreIsMore value.
OPERATION="COMPUTE" |
Run the Target Routine <MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="COMPUTE"/> Reject the current trial result and run the target routine <MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="COMPUTE" REJECTRESULT="Yes"/> Reject the current trial result, compute a new maximum and run the target routine <MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="COMPUTE" REJECTRESULT="Yes" LIMIT="Max"/> Reject the current trial result, compute a new minimum and run the target routine <MathVariable VARIABLENAME="TargetA" TYPE="TARGET" OPERATION="COMPUTE" REJECTRESULT="Yes" LIMIT="Min"/> |
Querying the Target Object
The Target object can be queried using the below fields. The OBJECTFIELD type is sued to access these values.
- NextTrialAmount : DECIMAL
- RevisedMaximumTrialAmount : DECIMAL
- RevisedMinimumTrialAmount : DECIMAL
- Status : INTEGER
In addition, the below Target status values should be defined in the target object and available through its properties.
- STATUSSuccess : INTEGER
- STATUSFailure : INTEGER
- STATUSTrial : INTEGER
- IsStatusSuccess : BOOLEAN
- IsStatusFailure : BOOLEAN
- IsStatusTrial : BOOLEAN
Note: The last three require the ability to use the BOOLEAN datatype
SOURCEOBJECT="Target" |
<MathVariable VARIABLENAME="TrialAmount" TYPE="OBJECTFIELD" SOURCEOBJECT="TargetA" DATATYPE="DECIMAL">NextTrialAmount</MathVariable> <MathVariable VARIABLENAME="TrialStatus" TYPE="OBJECTFIELD" SOURCEOBJECT="TargetA" DATATYPE="DECIMAL">STATUSTrial</MathVariable> <MathVariable VARIABLENAME="Status" TYPE="OBJECTFIELD" SOURCEOBJECT="TargetA" DATATYPE="DECIMAL">Status</MathVariable> <MathIF IF="TrialStatus = Status"> |
Rounding
The Target object is responsible for rounding each trial amount (if ROUNDTRIALS=Yes) and the final amount in case of success. However, it’s often useful to set the Target object to round a value according to its Precision and MoreIsMore. For instance, in case of failure, it may need to round the revised minimum or maximum, depending on various conditions.
<MathVariable VARIABLENAME="RoundedValue" TYPE="TARGET" OPERATION="ROUND" SOURCEOBJECT="TargetA">RawValue</MathVariable> |
Example
<!-- Find the cube root of 50,000 by using a TARGET type variable --> <TargetExample> <!-- Make at most 200 attempts at guessing the answer --> <MathVariable VARIABLENAME="Trials" TYPE="EXPRESSION" DATATYPE="INTEGER"> 200 </MathVariable> <!-- Create the TARGET variable, giving the desired result in the tag content --> <MathVariable VARIABLENAME="DesiredResult" TYPE="VALUE" DATATYPE="DECIMAL"> 50000 </MathVariable> <MathVariable VARIABLENAME="CubeRootTarget" TYPE="TARGET" OPERATION="CREATE" MAXTRIALS="Trials" MAXTRIALAMOUNT="100000" MINTRIALAMOUNT="0" MOREISMORE="Yes" ROUNDTRIALS="No"> DesiredResult </MathVariable> <!-- Add a hurdle --> <MathVariable VARIABLENAME="CubeRootTarget" TYPE="TARGET" OPERATION="ADDHURDLE" HURDLENAME="Power3Hurdle" HURDLETYPE="NUMERIC" TOLERANCE="Tolerance"> HurdleValue </MathVariable> <!-- Loop until either the TARGET tells us to stop or until we've reached our trial limit --> <MathLoop VARIABLENAME="TargetLoop" TYPE="FOR" ITERATIONS="Trials"> <!-- Query the TARGET object for the current trial amount and for the status --> <MathVariable VARIABLENAME="TrialAmount" TYPE="OBJECTFIELD" SOURCEOBJECT="CubeRootTarget" DATATYPE="DECIMAL"> NextTrialAmount </MathVariable> <MathVariable VARIABLENAME="TargetStatus" TYPE="OBJECTFIELD" SOURCEOBJECT="CubeRootTarget" DATATYPE="INT"> Status </MathVariable> <!-- Exit loop when done --> <MathVariable VARIABLENAME="Done" TYPE="EXIT-LOOP" IF="TargetStatus<>1" SOURCEARRAY="TargetLoop"/> <!-- If the status says to continue, set a new value for the hurdle and recompute --> <MathVariable VARIABLENAME="TrialResult" TYPE="EXPRESSION" DATATYPE="INTEGER"> TrialAmount ^ 3 </MathVariable> <MathVariable VARIABLENAME="CubeRootTarget" TYPE="TARGET" OPERATION="SETRESULT" HURDLENAME="Power3Hurdle"> TrialResult </MathVariable> <MathVariable VARIABLENAME="CubeRootTarget" TYPE="TARGET" OPERATION="COMPUTE"/> </MathLoop> </TargetExample> |