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.

  {
    "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. #

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.

  
  //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. #

Simulation States #

This SimulationStates object reports the series of states in a simulation life-cycle to generate a scenario.

  {
    "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. #

Progress #

This Progress object reports the current progress of a running scenario.

  {
    "Started": true,
    "Completed": false,
    "PercentComplete": 12,
    "TransactionCount": 12847,
    "SequenceCount": 832 
  }

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. #

Resources Forecast #

This ResourceRequirementsForecast object reports the results of the scenario. Definitions of each object can be found in Resource Requirements Forecast object reference.

  {
    "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.

[
  "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
    }
  ]
]

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.

  {
    "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
  }

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.

//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. #

TargetItemName - enum #

Numerical function that is evaluated. #

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.

  {
    "Type": "Model input error",
    "Message": "Processor Set Size must be positive at JE 2",
  }

Attributes #

Type - string #

Error type. #

Message - string #

Description of error. #