Appearance
Sensitivity Analysis Model Object Reference
Overview
Sensitivity analysis is a technique to help determine how output variables of a simulation are affected based on changes to input variables of a pool resource model (PRM), and is performed by running multiple simulations with these different values.
The challenge in performing a coherent analysis is identifying and organizing all the feasible property combinations as the number of variables to test increases. For example, targeting just two properties with a simple variation of plus/minus values of a property's baseline value requires nine simulations. The combination formula is Sn, where S is the property combination set size (i.e., baseline, plus, minus values) and n is the number of target properties. The required simulations therefore grows exponentially with the addition of more properties.
Compounding the challenge are properties that may have a mutual dependency, and targeting one property requires including this "linked" property - but which does not result in more combinations (i.e., number of required simulations).
Instead of manually building your variations to input variables and executing a simulation one at a time, you can automate your workflow using the utility endpoint create a property combination matrix. The endpoint accepts a SensitivityAnalysisModel object which you use to define the target input properties of your sensitivity analysis.
How to Perform a Sensitivity Analysis
These are basic steps your script needs to perform:
- Create a new SensitivityAnalysisModel object.
- Retrieve the PRM used for your target (baseline) scenario that has already been successfully completed (i.e., status 7). Add the PRM to the PoolResourceModel property in the SensitivityAnalysisModel object.
- Define the SensitivityModel object to identify the properties in the PRM that are the target of your sensitivity analysis. Add the model to the SensitivityModel property in the SensitivityAnalysisModel object.
- Execute the create a property combination matrix endpoint with the SensitivityAnalysisModel object included in the request body.
- Use the Key-Value array (i.e., the combination matrix response object of the endpoint) to set an outer loop for iterating over each Key.
- Use an inner loop for iterating over the Value array.
- For each item in the Value array, find the target property in the PRM using the FullPath property in the Value array. Replace the target PRM property value with the PropertyValue from the Value array item.
- Run a simulation per each set of changes made to the PRM (i.e., for each Value array per Key).
TIP
When executing a series of related simulations, use the "tag" query string parameter on the create a simulation endpoint to define a collection name. Use the search scenarios endpoint to query by this name.
- Upon completion of all simulations, build your sensitivity analysis by comparing rates of change to your output variables (e.g., core counts, a license counts, etc.).
Sensitivity Analysis Model
The SensitivityAnalysisModel is composed of two objects: 1) the PoolResourceModel, and 2) the SensitivityModel. The former represents a PRM that has already been the basis for a successfully completed simulation and now represents your "baseline" results.
json
{
"PoolResourceModel": {..},
"SensitivityModel": [..]
}
Because the PRM is the basis for your baseline results, the PRM is already validated and can be used as the model for which the SensitivityModel itself can be reliably validated against. Therefore, the following documentation focuses solely on defining the SensitivityModel object. Click here for documentation of the Pool Resource Model object.
Sensitivity Model Object
The SensitivityModel object identifies target input variables, their location (i.e., path) in the baseline PRM, how property value variation is constructed, and "edge case" properties identified by the Linked property.
json
[
{
"Path": "JumpEvents[1]",
"PropertyName": "TriggerTime",
"PlusMinusPercent": 10,
"NumericType": "Decimal",
"EventType": "Performance",
"EventId": 2,
"Linked": {
"Path": "JumpEvents[0]",
"EventType": "Configuration",
"Id": 1
}
},
{
"Path": "JumpEvents[1]",
"PropertyName": "PerformanceJumpPercent",
"PlusMinusPercent": 10,
"EventType": "Performance",
"EventId": 2
}
]Attributes
Path - string - required
The JSON member hierarchical path used to locate a specific property.
PropertyName - string - required
The JSON property name used for sensitivity analysis.
PlusMinusPercent - numeric - required
The percentage used to construct variation.
NumericType - numeric - optional
Specifies how the calculated variation value is rounded. 'Decimal' produces a result rounded to the 100th degree (ie., 0.01). 'Integer' produces a result rounded to the smallest integral value greater than calculated value (e.g., 15.3 to 16). 'Decimal' is the default.
WARNING
If a numeric type is selected that is inconsistent with the property's expected numeric type in the Pool Resource Model, the model will likely fail validation when executing the simulation.
EventType - string - required if referring to a jump event
Jump event event type property as array, where the array number is the index position of the jump event in the PRM.
EventId - integer - required if referring to a Jump Event
Jump event id number.
Linked - object - conditionally required
Linked object is the associated property, which is defined by PropertyName. In the response object, each will have the the same computed value for their respective PropertyValue property.
Common Edge Case
When the PRM includes both a Performance JE, with PerformanceType 'Server', and an associated Configuration JE (i.e., both events occur at the same trigger time), then the Sensitivity Model needs to account for their linked association.
In the response object, the trigger times for both Performance and Configuration JEs are always the same. See example in the response object below.
Path - conditionally required
The JSON member hierarchical path used to locate the linked property.
EventType - conditionally required
Jump event event type of the linked property.
Id - conditionally required
Jump event id number of the linked property.
How a Property Combination Matrix is Produced
Value variation is specified using the PlusMinusPercentage property, which will result in three different values that form a sensitivity item:
- existing property value defined in the PRM
- a lower value that is calculated by applying the PlusMinusPercentage property
- a higher value that is calculated by applying the PlusMinusPercentage property
Each sensitivity item, and its members, are automatically numbered. For example, in the request object example above, the first sensitivity item in the model targets the PropertyName of 'TriggerTime', which is a member of the Jump Event at index 1 in the baseline PRM. Using the create a property combination matrix, Zypr will internally generate a sensitivity item:
| Property | Data Source | Path | Set | Code | Property Value |
|---|---|---|---|---|---|
| TriggerTime | PRM | JumpEvents[1] | 1 | 1.1 | 1.0 |
| TriggerTime | Calculated using SM & PRM values | JumpEvents[1] | 1 | 1.2 | 0.9 |
| TriggerTime | Calculated using SM & PRM values | JumpEvents[1] | 1 | 1.3 | 1.1 |
The first line is the original baseline value from the baseline PRM. The second and third calculated values are variations of the baseline value based on the specified PlusMinusPercentage value. The Code value in the above table is used to construct a key representing a unique combination of property values.
The Key-Value-Pair of combinations can be viewed in the response object of the create a property combination matrix below. Normally, the number of codes combined in the Key property will equal the number of items in the Value array object. The exception is when a Linked item is specified. Recall, the inclusion of a Linked item doesn't increase the number of unique combinations; it simply accompanies a targeted property and its property value must change in sync with its parent property's value. So instead of variations for three properties resulting in 27 unique combinations, this example sensitivity model remains at nine unique combinations, but has three properties in Value array (yet only two Code items in the Key).
json
//excerpt of Jump Event objects from Pool Resource Model
"JumpEvents": [
{
"EventId": "1",
"EventType": "Configuration",
"ServerCost": 14000,
"ServerSize": 2,
"CoreSetSize": 48,
"ServerWatts": 420,
"TriggerTime": 1.5,
"ProcessorSetSize": 2
},
{
"EventId": "2",
"EventType": "Performance",
"TriggerTime": 1.5,
"PerformanceType": "Server", //performance jump due to a server
"PerformanceJumpPercent": 88.6
},
]Response Object
json
[
{
"Key": "1.1,2.1", //combination set of two target variables
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.5
},
//This entry is the linked Configuration JE
//It will always mirror the Performance JE to which it is linked
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.5
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 88.6
}
]
},
{
"Key": "1.1,2.2",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.5
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.5
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 79.74
}
]
},
{
"Key": "1.1,2.3",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.5
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.5
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 97.46
}
]
},
{
"Key": "1.2,2.1",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 88.6
}
]
},
{
"Key": "1.2,2.2",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 79.74
}
]
},
{
"Key": "1.2,2.3",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.35
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 97.46
}
]
},
{
"Key": "1.3,2.1",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 88.6
}
]
},
{
"Key": "1.3,2.2",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 79.74
}
]
},
{
"Key": "1.3,2.3",
"Value": [
{
"FullPath": "JumpEvents[1].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[0].TriggerTime",
"PropertyValue": 1.65
},
{
"FullPath": "JumpEvents[1].PerformanceJumpPercent",
"PropertyValue": 97.46
}
]
}
]