Appearance
Scenario Object Reference
The output of a simulation is referred to as a scenario. This Scenario object is the response object to the POST endpoint of Create a scenario and the GET endpoint of Scenario record. The content of a Scenario object will vary depending on the state of a simulation or the result of a simulation
A simulation request is a long-running operation that involves multiple steps. The current (or last) status of a simulation is shown in the StatusNbr and StatusDescription properties. The life-cycle of simulation status is contained in the SimulationStates object. A simulation in a running state (i.e., status number 6), will report progress metrics in the Progress object.
Simulation life-cycle
A request to create a scenario is managed as a long-running task comprises a series of steps. At each step, the state of your request is persisted. A successfully completed simulation follows this order:
- Receive a simulation request which includes a Pool Resource Model.
- Submitted model is validated.
- Validated model is placed into simulator queue to await execution.
- Queue manager starts a unique instance of the simulator for executing your request.
- Running simulation reports its status.
- Simulator reports completion of your request.
Your request to create a new scenario will return a Scenario response object after a failed model validation or after your request has successfully been added to the simulator queue. If the former, the simulation life-cycle has reached completion. If the latter, your request has been handed off to a different host environment where the queue manager resides and simulations are executed. As a Zypr user, you do not have access to this environment.
In the returned Scenario object, you will find the Id property which is a unique value generated for every "Create a scenario" request. If a model fails validation, is corrected, and then resubmitted, a new scenario Id will be generated.
The scenario Id is used to pool a running simulation and retrieve a finalized scenario object using the endpoint /v1/simulations/{scenarioId}. You can also elect to have a completed scenario object emailed to you by setting the EmailResults property to true.
json
{
"Id":"do.vj5rf3xjrgsvhzzuqejwa",
"Timestamp": "2023-02-07T11:17:42Z",
"UserName": "sallydoe@company.com",
"StatusNbr": 2,
"StatusDescription": "Request started",
"Settings": null,
"SimulationStates": [
{
"StatusTimestamp" : "2023-03-31T22:28:44Z",
"StatusNbr" : 2,
"Message" : "Request started"
},
{
"StatusTimestamp" : "2023-03-31T22:28:43Z",
"StatusNbr" : 1,
"Message" : "Received request"
}
],
"Progress": null,
"ResourceRequirementsForecast": null,
"Calendars": null,
"NoSolutionGraphs": null,
"Errors": null,
"ValidationPassed" : null,
"ValidationResults" : null,
}
Attributes
Id - string
Uniquely identifies a scenario. Each simulation request receives a new scenario Id.
Timestamp - datetime
Timestamp when this scenario record was requested and reported to you. See SimulationStates for timestamps corresponding to scenario creation.
UserName - string
User who requested the creation of this scenario.
StatusNbr - integer
Status number of the most recent simulation state.
StatusDescription - string
Status description of the most recent simulation state.
Settings - object
Contains user provided values received from the Settings object of the submitted model. Zypr adds several properties to this object and returns this updated object.
SimulationStates - array of objects
Identifies the various states of a simulation task. A request is managed as an on-demand task. An error-free request proceeds through states 1 - 7. Any state above 7 indicates a state in which a task cannot be completed and a scenario cannot be generated. Progress of a running simulation (state 6) can be polled using the Progress object.
Progress - object
Description of progress and transactional statistics of a running simulation. Available when Simulation State is 6 or 7.
ResourceRequirementsForecast (RRF) - array of objects
Object that contains a preferred result with respect to the type of simulation selected. The object is a collection of key performance metrics and time-series forecasts for each pool resource.
Time-Series Collection Items
- Financial Stats
- Financial Summary
- Hardware Stats
- Hardware Summary
- Hardware Transactions
- Software Stats
- Software Summary
- Software Transactions
- Facility Stats
- Facility Summary
- Facility Transactions
ResourcesCalendars - array of objects
Object that contains generated calendars. Calendars are currently only generated for software resources.
NoSolutionGraphs - array of objects
A list of graph objects for which a solution was not found. A graph with no solution may arise when the model includes a Constraints object.
ValidationPassed - boolean
Convenience property indicating if content of ResourceRequirementsForecast object passed all validations.
ValidationResults - array of object
Validity inspection of ResourceRequirementsForecast (RRF).
Purpose of RRF validation
Executing a simulation involves blending discrete events, along with a mix of integers and real numbers, to create a smooth evolution. This necessitates rounding strategies to reliably evolve pool state over time. Zypr performs a series of inspections to validate that process.
A failed validation means the reported result did not meet the expected result with the tolerance level specified. Whether that tolerance level is appropriate for your needs, only you can determine.
json
//example of validation result item
{
"ResultItemName": "FinancialSummary", //series in RRF
"TargetItemName": "HorizontalCumulative", //what's inspected
"Passed": true,
"ToleranceLevel": ".00100" //rounding tolerance used
}
Errors - array of objects
List of scenario error descriptions.
Settings
This Settings object includes properties received from the submitted Pool Resource Model Settings object.
Zypr adds two generated date properties highlighted in the code block below. The ModelStartDate property value is conditionally determined.
json
//user specified ModelEffectiveDate property
{
"ScenarioName": "My Scenario Name",
"ModelEffectiveDate": "2023-01-27T00:00:00Z", //date set by user
"ModelStartDate": "2023-01-27T00:00:00Z", //date set by Zypr
"ScenarioCreatedDate": "2023-02-07T11:17:42Z", //date set by Zypr
"EmailResults": true,
"Pool": {
"Id": "ATL1_42_PROD",
"Name": "Name of service pool",
"Description": "A long description of pool"
},
}
//a ModelEffectiveDate property was not specified by user
{
"ScenarioName": "My Scenario Name",
"ModelEffectiveDate": null,
"ModelStartDate": "2023-02-07T11:17:42Z", //date set by Zypr
"ScenarioCreatedDate": "2023-02-07T11:17:42Z", //date set by Zypr
"EmailResults": true,
"Pool": {
"Id": "ATL1_42_PROD",
"Name": "Name of service pool",
"Description": "A long description of pool"
},
}
Attributes (added by Zypr)
ModelStartDate - date
This is the starting date of the time-series forecast contained in ResourceRequirementsForecast object. If a valid ModelEffectiveDate was received from the Pool Resource Model Settings object, then the ModelStartDate property is set to this date. If a valid ModelEffectiveDate was not received, then the ModelStartDate is set to the ScenarioCreateDate property value.
ScenarioCreateDate - date
This is the date when the simulator starts a new simulation task.
SimulationStates
This SimulationStates object reports the series of states in a simulation life-cycle to generate a scenario.
json
{
"StatusTimestamp" : "2023-03-31T22:28:58Z",
"StatusNbr" : 3,
"Message" : "Model validation succeeded"
}
Attributes
StatusTimestamp - datetime in UTC
Indicates when the state was posted.
StatusNbr - integer
The status number that corresponds to a simulation state.
Message - string
Describes the simulation state that corresponds to the status number.
Common State Numbers and Description
| Nbr | Description |
|---|---|
| 1 | Received request |
| 2 | Start request initiated |
| 3 | Model validation succeeded |
| 4 | Request added to simulator queue |
| 5 | Simulator verified start |
| 6 | Simulator is executing |
| 7 | Simulator completed |
| 9 | Request exceeds user's rate limit |
| 14 | Model validation failed |
| 15 | No solution found compliant with constraints |
| 16 | No solution found |
Progress
This Progress object reports the current progress of a running scenario.
json
{
"Started": true,
"Completed": false,
"PercentComplete": 12,
"TransactionCount": 12847,
"SequenceCount": 832
}
TIP
To poll the status of a running scenario use GET Scenario record endpoint in Simulations
Attributes
Started - boolean
Indicates the simulator has a valid input model to work with and construction of a scenario has commenced.
Completed - boolean
The simulator has completed and generated a scenario or encountered an error.
PercentComplete - integer
Estimate of progress to generate a scenario.
TransactionCount - integer
Estimate of feasible server add/remove transactions .
TransactionCount - integer
Estimate of feasible transactions corresponding to precision level of a simulation.
SequenceCount - integer
The number of permutations of distinct refresh rates (i.e., a choose rate), applied to hardware inventory, drawn from a defined set of draw rates which correspond to model precision.
Fixed Time vs Optimal Yield Simulations
A Fixed Time simulation produces a sequence count of one, which reflects a single rule (e.g., refresh server every 5 years) that produces a sequential order of removal with respect to server chronological age.
An Optimal Yield simulation identifies the order of removal with respect to lowest total resource cost. Zypr therefore seeks to identify a range of transactions and corresponding sequences that produces feasible transactional sequences that minimize total cost. The precision level of this type of simulation process corresponds to the set of draw rates (i.e., removal rates from the pool) specified for the simulation.
If you need a higher degree of computational precision than the default setting, please reach out to us. Controlling the precision level is an advanced feature that can be setup for your unique needs.
Resources Forecast
This ResourceRequirementsForecast object reports the results of the scenario. Definitions of each object can be found in Resource Requirements Forecast object reference.
json
{
"FinancialStats": {},
"FinancialSummary": {},
"HardwareStats": {},
"HardwareSummary": {},
"HardwareDetail": {},
"SoftwareStats": {},
"SoftwareSummary": {},
"SoftwareDetail": {},
"FacilityStats": {},
"FacilitySummary": {},
"FacilityDetail": {}
}
Calendars
This Calendars object reports each resource calendar, and their respective schedules, that Zypr generated. Currently, the Calendars feature is only available for software resources, and only those software items with a Contract Type of 'Coterminous'.
If the CostRules object was used to define a fee schedule or fixed duration charge rule, the generated values are included in the Schedules array.
json
[
"Type": "Software"
"CalendarBasis" : "Union",
"LicenseId" : 1,
"LicenseClass" : "Perpetual",
"LicenseMetric" : "Processor",
"Schedules": [
{
"Type": "TrueUp",
"TimeStart": -0.42,
"TimeEnd": 0.58,
"Duration": 1.00,
"DateStart": "2022-07-31",
"DateEnd" : "2023-07-31",
"Fee":1000,
"PerpetualSupportPercent": 25,
"FixedDuration": 50
},
{
"Type": "Contract",
"IsAnnualTrueUp": true,
"TimeStart": 0.58,
"TimeEnd": 1.58,
"Duration": 1.00,
"DateStart": "2023-07-31",
"DateEnd" : "2024-07-31",
"Fee": 1050,
"PerpetualSupportPercent": 25,
"FixedDuration": 50
}
]
]
TIP
When Zypr builds a schedule, the model start date is treated as time zero. A schedule's initial interval will therefore have a TimeStart property value that precedes the model start date and will be negative.
Attributes
Type - string
Indicates the calendar type (i.e., TrueUp, Contract).
IsAnnualTrueUp - boolean
Indicates if Type property, with value 'Contract', is also treated as an annual true-up.
CalendarBasis - string
The technique used to construct the schedule.
LicenseId - integer
Integer that represents a unique software item.
LicenseClass - string
Type of license (i.e., perpetual, subscription).
LicenseMetric - string
Hardware item used by a vendor for counting license consumption (i.e., server, processor, core).
Schedules - array of objects
List of schedule intervals
TimeStart - numeric
Start time of interval expressed in years (endpoint inclusive).
TimeEnd - numeric
End time of interval (endpoint exclusive).
Duration - numeric
Interval length of time in years (i.e, TimeEnd minus TimeStart).
DateStart - date
Start date of interval
DateEnd - date
End date of interval
Fee - numeric
Vendor fee for perpetual license or annual subscription fee.
PerpetualSupportPercent - numeric
Vendor annual fee for perpetual license support, expressed as a percentage of current license fee.
FixedDurationPercent - numeric
Vendor fixed duration usage charge for incremental perpetual support or subscription license. Percentage is applied to interval duration of the selected schedule (e.g., 50% applied to an annual true-up schedule result in a 6 month fixed charge regardless of actual length of use during the schedule interval).
No Solution Graphs
This NoSolutionGraphs object may list of one or more graphs that failed because a solution could not be found for that graph. If the Constraints object is used to constrain the feasible solution space, it is likely the object has a value that is too restrictive.
json
{
"FailedGraphNbr": 9,
"EdgeNbr" : 0,
"NodeY" : 0,
"NodeX" : 0,
"Message:" "Your constraint is too restrictive.
No graph solution compliant with constraint."
"AtRelativeTargetTime": 0.0,
"AtAbsoluteTargetTime": 0.0,
"LowestConstraintMetricVarianceRate": 0.0,
"StackTrace": null,
"NonCompliantSequences": null
}
Interpreting NoSolutionGraphs
To understand why a constraint failed to produce a solution, you need to know a bit more about how Zypr builds feasible solutions. Zypr uses graphs to build time-series forecasts. A graph contains edges and nodes and are used to define locations for time-based intervals.
The code block above indicates the solution space for Graph 9 is empty. This graph failed immediately at start time 0.0, indicated by both the AtRelativeTargetTime and AtAbsoluteTargetTime at 0.0, and the graph's EdgeNbr, and node address at NodeY, and NodeX, which are both 0.
Alternatively, you may set a constraint that turns out to be too limiting at a future time, for example, at an absolute target time of 1.5 years and a relative time of .25. The absolute time corresponds to the duration with respect to scenario's actual start time of 0. Whereas the relative time corresponds to the time within a particular edge, which corresponds to one or more Jump Events you specified in the Pool Resource Model.
Attributes
FailedGraphNbr - integer
The graph number the simulation engine attempted to build, but failed.
EdgeNbr - integer
Edge number of graph.
NodeY - integer
Node Y dimension of edge number.
NodeX - integer
Node X dimension of edge number.
Message - string
Description of failure.
AtRelativeTargetTime - numeric
Time (yrs) of failure relative to the edge number.
AtAbsoluteTargetTime - numeric
Time (yrs) of failure in absolute time.
LowestConstraintMetricVarianceRate - numeric
Variance from the target constraint.
Errors
This Error object identifies and describes one or more errors.
json
{
"Type": "Model input error",
"Message": "Processor Set Size must be positive at JE 2",
}
INFO
The code block above indicates the received PoolResourceModel object failed validation. The Message description refers to a jump event (JE) number 2, which refers to its EventId in the Jump Events object.