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 Simulation States 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",
"UserId": "2268cf84-9c28-485e-ba68-6d3e162c80a1",
"StatusNbr": 2,
"StatusDescription": "Request started",
"Settings": null,
"SimulationStates": [..],
"Progress": [..],
"ResourceRequirementsForecast": null,
"CalendarizedForecast": 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 corresponding to the final simulation state (see SimulationStates) received from simulator.
UserId - string
Id of user who requested the creation of 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
Property indicating if content of ResourceRequirementsForecast object passed all validations.
ValidationResults - array of object
Validity inspection of ResourceRequirementsForecast (RRF).
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", //was set by user
"ModelStartDate": "2023-01-27T00:00:00Z", //set by Zypr
"ScenarioCreatedDate": "2023-02-07T11:17:42Z", //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, //was not set by user
"ModelStartDate": "2023-02-07T11:17:42Z", //set by Zypr
"ScenarioCreatedDate": "2023-02-07T11:17:42Z", //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 timestamp when the task queue scheduler starts a new container and a new simulator is initialized.
Simulation States
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 | Request started |
| 3 | Model validation succeeded |
| 4 | Request added to simulator queue |
| 5 | Simulator has started |
| 6 | Simulator is executing |
| 7 | Simulator completed |
| 10 | Request exceeds user's rate limit |
| 11 | Model validation failed |
| 12 | No solution found compliant with constraints |
| 13 | 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 the 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 vs Optimal Simulations
A Fixed 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 simulation identifies the order of removal with respect to lowest total resource cost. Zypr therefore seeks to evaluate countless 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": []
}
Calendarized Forecast
This CalendarizedForecast object reports the Resource Requirements Forecast transformed into a time-series whose intervals are based on calendar months.
json
{
"ReportStartDate": "2024-06",
"ReportEndDate": "2026-12",
"ResourceType": "All",
"ScenarioIds": [],
"Financial":[
{
"ReportPeriod": 2024-10,
"ReportPeriodStart": "2024-10-1",
"ReportPeriodEnd": "2024-10-31",
"PeriodNbr": 5,
"Server": 96000,
"Assignment": 4000,
"PerpetualLicense": 0,
"Support": 25600,
"Subscription": 65000,
"SoftwareTotal": 90600,
"Power": 5742,
"Facility": 3750,
"Total": 200092
}
],
"HardwareInventory": [
{
"ReportPeriod": 2024-10,
"ReportPeriodStart": "2024-10-1",
"ReportPeriodEnd": "2024-10-31",
"PeriodNbr": 5,
"RackQtyStart": null,
"RackQtyEnd": null,
"ServerQtyStart": 250,
"ServerQtyEnd": 240,
"ProcessorQtyStart": 500,
"ProcessorQtyEnd": 480,
"CoreQtyStart": 8000,
"CoreQtyEnd": 7680:
},
],
"HardwareTransactions" : [
{
"ReportPeriod": 2024-10,
"ReportPeriodStart": "2024-10-1",
"ReportPeriodEnd": "2024-10-31",
"PeriodNbr": 5,
"RackQtyAdds": null,
"RackQtyRemovals": null,
"ServerQtyAdds": 30,
"ServerQtyRemovals": -40,
"ProcessorQtyAdds": 60,
"ProcessorQtyRemovals": -80,
"CoreQtyAdds": 960,
"CoreQtyRemovals": -1280:
},
],
"SoftwareInventory": [
{
"ReportPeriod" : 2024-10,
"ReportPeriodStart": "2024-10-1",
"ReportPeriodEnd": "2024-10-31",
"PeriodNbr": 5,
"Stack": [
{
"LicenseId": 1,
"LicenseType": "Subscription",
"LicenseMetric": "Processor",
"ContractType": "Coterminous",
"RequiredQtyStart": 500,
"RequiredQtyEnd": 480,
"AvailableQtyStart" : 520,
"AvailableQtyEnd": 520,
"ExcessQtyStart": 20,
"ExcessQtyEnd": 40,
}
]
},
],
"FacilityResources": [
{
"ReportPeriod": 2024-10,
"ReportPeriodStart": "2024-10-1",
"ReportPeriodEnd": "2024-10-31",
"PeriodNbr": 5,
"RackUnitSlotQtyStart": 250,
"RackUnitSlotQtyEnd": 240,
"KilowattsHrs": 63798
},
]
"ErrorMessage" : null
}Rounding precision
Transforming intervals contained in a Resource Requirements Forecast (RRF) time-series (domain A) into a time-series based on calendar intervals (domain B) requires mapping one-to-many and many-to-one interval relationships. For example, a single RRF interval may span multiple months, or conversely, multiple RRF intervals may fall within a single month.
For values expressed as a real number (e.g., financial costs, power consumption, etc.), the mapping process requires rounding and therefore causes rounding errors, typically less than 1%. Specifically, the sum of a property, whose value is a real number, is highly unlikely to exactly match its corresponding cumulative property value contained in the ResourceRequirementsForecast object.
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.
Validation of Results
This ValidationResults object identifies a list of tests that are performed to validate the evolution process.
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 within the tolerance level specified. Whether that tolerance level is appropriate for your needs, is for you to determine.
json
//example of validation result item
{
"ResultItemName": "FinancialSummary", //series in RRF
"TargetItemName": "HorizontalCumulative", //what's inspected
"Passed": true,
"ToleranceLevel": .00100 //rounding tolerance used
}Attributes
ResultItemName - enum
The target subject of validation.
Result Item Names
| Result Item | Description |
|---|---|
| GraphFramework | Graph framework used to construct simulation scaffolding |
| HardwareSummary | Summary of server or rack hardware inventory balances at each interval |
| HardwareTransactions | Detail of hardware add/remove transactions at each interval |
| SoftwareDetail | Detail of required software licenses or subscriptions transactions and balances at each interval |
| FinancialSummary | Summary of costs associated with required resource provisioning at each interval |
TargetItemName - enum
Numerical function that is evaluated.
Target Item Names
| Inspected Item | Description |
|---|---|
| IntervalNumbers | Number representing an interval of evolution process |
| IntervalTime | Start and end time of interval |
| IntervalSequenceNbr | Ordered interval number |
| Demand | Service demand or load |
| UtilizationPercent | Upper, lower or current utilization rate of pool hardware |
| Perf | Scaler performance rating of a server (i.e., weighting factor) |
| PerfTotal | Aggregation of scalar performance |
| Quantity | A unit measure of software license or subscription |
| HorizontalCumulative | Sum of values of current interval |
| VerticalCumulative | Sum of values carried-forward from one interval to the next |
| LotUnit | Transactions per type of inventory lotting |
| ServerQty | Server inventory balances |
| RackQty | Rack inventory balances |
| AssignmentEvent | Add/Removal transactions |
Passed - boolean
Status of validation.
ToleranceLevel - numeric
Tolerance value used to determine if Target Item passes validation.
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.