POST api/v0/Simulation?apiKey={apiKey}&lang={lang}
Uploads the portfolio details to the server in order to simulate it. Once uploaded, the Calculation Manager creates a calculation job and returns the details.
Request Information
URI Parameters
| Name | Description | Type | Remarks |
|---|---|---|---|
| apiKey |
Required A unique identifier that serves as a form of authentication that verifies the identity of the user making the API request. See the documentation for more details. |
string | |
| lang |
The expected locale of the output, e.g. 'en' or 'de'. |
string |
Body Parameters
Portfolio details.
SimulationParameters| Name | Description | Type | Remarks |
|---|---|---|---|
| SimulationRuns |
Required The number of simulation runs. The recommended range is 10,000 to 100,000 simulation runs. A higher number of simulation runs is not practically effective. It is important to note that more simulation runs require additional time to complete the simulation. |
uint |
Required Range: [10, 1000000] |
| YearsNumber |
Required The number of years (periods) to be simulated. Please ensure that the corresponding number of years is provided in the quantification parameters for each risk. |
int |
Range: [1, 100] |
| Risks |
Required A collection of risks to be simulated. Must contain at least one risk. |
List<SimulationRisk> |
Min count: 1 |
| TotalPeriod |
A Boolean that indicates whether the statistics for the entire period is calculated. For instance, if the portfolio includes three years, the statistics for the total period aggregates years one, two and three. Note that enabling this property is only relevant if the number of years is greater than 1. Otherwise, the statistics for the total period is equivalent to those of the first year. |
boolean |
Default value: False. |
| AggregatedPeriods |
A Boolean that indicates whether the statistics for the aggregated periods is calculated. Unlike the parameter TotalPeriod, which only enables the statistics for the entire period, this parameter enables the statistics for all intermediate periods. For example, if the portfolio includes three years, enabling this flag allows the calculation of aggregated statistics for years one-two and years one-two-three. Note that enabling this parameter will override the parameter TotalPeriod, as the aggregated statistics over all intermediate years is equivalent to the statistics for the entire period. |
boolean |
Default value: False. |
| IsRiskPositive |
A Boolean that indicates whether the risks are positive (true) or negative (false). In the case of positive risks, higher (positive) numbers correspond to risks, while lower (negative) numbers represent opportunities. Conversely, for negative risks, the relationship is exactly the opposite. |
boolean |
Default value: False. |
| Sensitivity |
The settings for the sensitivity analysis. |
SensitivitySettings | |
| Statistics |
The statistics to be calculated. |
List<StatisticsType> |
Default is Mean and STD. |
| Percentiles |
A list of percentiles in [0, 1] used for calculating VaR and CVaR. |
List<double> |
No percentiles are calculated by default. |
| ChartSettings |
The chart settings. |
ChartSettings | |
| UseInitialSeed |
A Boolean that indicates if the seed of the random generator must be reset before the simulation. If set to True, the simulation will produce identical results when using the same input settings. |
boolean |
Default value: False. |
| KeepLosses |
A Boolean that indicates whether the risk losses are retained after the simulation and included in the results. Note that enabling this option significantly increases the size of the resulting data stream as it includes all intermediate results produced during the simulation. It is recommended to keep it disabled (omit the property or set to false). |
boolean |
Default value: False. |
| ProfitLossStatement |
A Profit and Loss (P&L) statement. |
ProfitLossStatement | |
| Indicators |
A collection of portfolio indicators. |
List<Indicator> | |
| Levels |
A collection of Risk Bearing Capacity levels. |
List<Level> | |
| Properties |
A collection of custom key-value properties. Use this collection to hand over the internal state of the model. The keys in the collection must be unique. |
Dictionary<string, Object> |
Request Formats
URL
Body (application/json, text/json)
{
"SimulationRuns": 25000,
"YearsNumber": 2,
"TotalPeriod": false,
"AggregatedPeriods": false,
"IsRiskPositive": true,
"Sensitivity": {
"Calculate": true,
"Percentile": 0.995
},
"Statistics": [
2,
4
],
"Percentiles": [
0.9,
0.95,
0.99,
0.999
],
"ChartSettings": {
"Width": 720,
"Height": 540,
"MaxPercentile": 1,
"Unit": "",
"SensitivityBars": 10,
"SensitivityRows": 10,
"BinsCount": 50,
"ExportType": 3,
"RiskMapConfigurations": [ ],
"CategoricalRiskMapConfigurations": [ ],
"YearHeaders": { },
"TotalHeader": "",
"Layouts": [ ],
"Styles": { }
},
"Risks": [
{
"ID": "1",
"SecondaryID": "0",
"Name": "Security risk",
"Description": "",
"RiskYears": [
{
"CustomPropertyIDs": [ ],
"Distribution": {
"__type": "Normal",
"Parameters": [
[
100000
],
[
5000
]
]
},
"Frequency": {
"Type": 0,
"Value": 0.05,
"Minimum": 0,
"Maximum": 10,
"LengthOfPeriod": 1
}
},
{
"CustomPropertyIDs": [ ],
"Distribution": {
"__type": "Normal",
"Parameters": [
[
150000
],
[
10000
]
]
},
"Frequency": {
"Type": 0,
"Value": 0.05,
"Minimum": 0,
"Maximum": 10,
"LengthOfPeriod": 1
}
}
],
"Partitions": [
{
"ID": 0,
"Name": "Overall",
"Type": "Overall"
}
],
"Positions": [ ],
"ConsecutiveRisks": [ ],
"NegativeDependencies": [ ]
},
{
"ID": "2",
"SecondaryID": "0",
"Name": "Equipment damage",
"Description": "",
"RiskYears": [
{
"CustomPropertyIDs": [ ],
"Distribution": {
"__type": "Normal",
"Parameters": [
[
75000
],
[
8000
]
]
},
"Frequency": {
"Type": 0,
"Value": 0.05,
"Minimum": 0,
"Maximum": 10,
"LengthOfPeriod": 1
}
},
{
"CustomPropertyIDs": [ ],
"Distribution": {
"__type": "Normal",
"Parameters": [
[
90000
],
[
9000
]
]
},
"Frequency": {
"Type": 0,
"Value": 0.05,
"Minimum": 0,
"Maximum": 10,
"LengthOfPeriod": 1
}
}
],
"Partitions": [
{
"ID": 0,
"Name": "Overall",
"Type": "Overall"
}
],
"Positions": [ ],
"ConsecutiveRisks": [ ],
"NegativeDependencies": [ ]
}
],
"ProfitLossStatement": {
"Positions": [ ],
"Relations": [ ]
},
"Indicators": [ ],
"Levels": [ ],
"Properties": {
"CustomID": 99,
"CustomTitle": "Monthly analysis"
}
}
Response Information
Resource Description
The object that includes the information about the newly created calculation job.
SimulationParametersResponse| Name | Description | Type | Remarks |
|---|---|---|---|
| ID |
The ID of the newly created simulation request. The ID is then used to obtain the simulation results. |
int | |
| Success |
A Boolean that indicates if the simulation is registered successfully. |
boolean | |
| Error |
The error message if any. Returns empty string if the operation has succeeded. |
string |
Response Formats
Body (application/json, text/json)
{
"ID": 123,
"Success": true,
"Error": ""
}