Scenario Module

This section documents the scenario components of the Nextmv Cloud API.

scenario

This module contains definitions for scenario tests.

CLASS	DESCRIPTION
ScenarioConfiguration	Configuration for a scenario with multiple option values.
ScenarioInputType	Enumeration of input types for a scenario.
ScenarioInput	Input to be processed in a scenario.
Scenario	A test case for comparing a decision model with inputs and configurations.

Scenario dataclass

Scenario(
    scenario_input: ScenarioInput,
    instance_id: str,
    scenario_id: Optional[str] = None,
    configuration: Optional[
        list[ScenarioConfiguration]
    ] = None,
)

A scenario is a test case that is used to compare a decision model being executed with a set of inputs and configurations.

You can import the Scenario class directly from cloud:

from nextmv.cloud import Scenario

A scenario encapsulates all the necessary information to run a test case against a decision model. Each scenario includes input data, an instance ID, and can optionally include configuration options that define different variations of the run.

PARAMETER	DESCRIPTION
scenario_input	Input for the scenario. The input is composed of a type and data. Make sure you use the ScenarioInput class to create the input. TYPE: ScenarioInput
instance_id	ID of the instance to be used for the scenario. TYPE: str
scenario_id	Optional ID of the scenario. The default value will be set as scenario-<index> if not set. TYPE: Optional[str] DEFAULT: None
configuration	Optional configuration for the scenario. Use this attribute to configure variation of options for the scenario. TYPE: Optional[list[ScenarioConfiguration]] DEFAULT: None

Examples:

>>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
>>> # Creating a simple scenario with an input set
>>> input_data = ScenarioInput(
...     scenario_input_type=ScenarioInputType.INPUT_SET,
...     scenario_input_data="input-set-id-123"
... )
>>> scenario = Scenario(
...     scenario_input=input_data,
...     instance_id="instance-id-456",
...     scenario_id="my-test-scenario"
... )
>>>
>>> # Creating a scenario with configuration options
>>> config_options = [
...     ScenarioConfiguration(name="solver", values=["simplex", "interior-point"]),
...     ScenarioConfiguration(name="timeout", values=["10", "30", "60"])
... ]
>>> scenario_with_config = Scenario(
...     scenario_input=input_data,
...     instance_id="instance-id-456",
...     configuration=config_options
... )

configuration class-attribute instance-attribute

configuration: Optional[list[ScenarioConfiguration]] = None

Optional configuration for the scenario. Use this attribute to configure variation of options for the scenario.

instance_id instance-attribute

instance_id: str

ID of the instance to be used for the scenario.

option_combinations

option_combinations() -> list[dict[str, str]]

Creates the combination of options that are derived from the configuration property.

This method calculates the cross-product of all configuration options to generate all possible combinations. If no configuration is provided, it returns a list with an empty dictionary.

RETURNS	DESCRIPTION
list[dict[str, str]]	A list of dictionaries where each dictionary represents a set of options derived from the configuration.

Examples:

>>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
>>> input_data = ScenarioInput(
...     scenario_input_type=ScenarioInputType.INPUT_SET,
...     scenario_input_data="input-set-id"
... )
>>> config = [
...     ScenarioConfiguration(name="x", values=["1", "2"]),
...     ScenarioConfiguration(name="y", values=["3", "4"])
... ]
>>> scenario = Scenario(
...     scenario_input=input_data,
...     instance_id="instance-id",
...     configuration=config
... )
>>> scenario.option_combinations()
[{'x': '1', 'y': '3'}, {'x': '1', 'y': '4'}, {'x': '2', 'y': '3'}, {'x': '2', 'y': '4'}]

Source code in nextmv/nextmv/cloud/scenario.py

def option_combinations(self) -> list[dict[str, str]]:
    """
    Creates the combination of options that are derived from the
    `configuration` property.

    This method calculates the cross-product of all configuration
    options to generate all possible combinations. If no configuration
    is provided, it returns a list with an empty dictionary.

    Returns
    -------
    list[dict[str, str]]
        A list of dictionaries where each dictionary represents a set of
        options derived from the configuration.

    Examples
    --------
    >>> from nextmv.cloud import Scenario, ScenarioInput, ScenarioInputType, ScenarioConfiguration
    >>> input_data = ScenarioInput(
    ...     scenario_input_type=ScenarioInputType.INPUT_SET,
    ...     scenario_input_data="input-set-id"
    ... )
    >>> config = [
    ...     ScenarioConfiguration(name="x", values=["1", "2"]),
    ...     ScenarioConfiguration(name="y", values=["3", "4"])
    ... ]
    >>> scenario = Scenario(
    ...     scenario_input=input_data,
    ...     instance_id="instance-id",
    ...     configuration=config
    ... )
    >>> scenario.option_combinations()
    [{'x': '1', 'y': '3'}, {'x': '1', 'y': '4'}, {'x': '2', 'y': '3'}, {'x': '2', 'y': '4'}]
    """

    if self.configuration is None or len(self.configuration) == 0:
        return [{}]

    keys, value_lists = zip(*((config.name, config.values) for config in self.configuration))
    combinations = [dict(zip(keys, values)) for values in itertools.product(*value_lists)]

    return combinations

scenario_id class-attribute instance-attribute

scenario_id: Optional[str] = None

Optional ID of the scenario. The default value will be set as scenario-<index> if not set.

scenario_input instance-attribute

scenario_input: ScenarioInput

Input for the scenario. The input is composed of a type and data. Make sure you use the ScenarioInput class to create the input.

ScenarioConfiguration dataclass

ScenarioConfiguration(name: str, values: list[str])

Configuration for a scenario.

You can import the ScenarioConfiguration class directly from cloud:

from nextmv.cloud import ScenarioConfiguration

You can define multiple values for a single option, which will result in multiple runs being created. For example, if you have a configuration option "x" with values [1, 2], and a configuration option "y" with values [3, 4], then the following runs will be created: - x=1, y=3 - x=1, y=4 - x=2, y=3 - x=2, y=4

PARAMETER	DESCRIPTION
name	Name of the configuration option. TYPE: str
values	List of values for the configuration option. TYPE: list[str]

Examples:

>>> from nextmv.cloud import ScenarioConfiguration
>>> config = ScenarioConfiguration(name="solver", values=["simplex", "interior-point"])

name instance-attribute

name: str

Name of the configuration option.

values instance-attribute

values: list[str]

List of values for the configuration option.

ScenarioInput dataclass

ScenarioInput(
    scenario_input_type: ScenarioInputType,
    scenario_input_data: Union[
        str, list[str], list[dict[str, Any]]
    ],
)

Input to be processed in a scenario.

You can import the ScenarioInput class directly from cloud:

from nextmv.cloud import ScenarioInput

The type of input is determined by the scenario_input_type attribute. The input can be a single input set ID, a list of input IDs, or raw data. The data itself of the scenario input is tracked by the scenario_input_data attribute.

PARAMETER	DESCRIPTION
scenario_input_type	Type of input for the scenario. This is used to determine how the input should be processed. TYPE: ScenarioInputType
scenario_input_data	Input data for the scenario. This can be a single input set ID (str), a list of input IDs (list[str]), or raw data (list[dict[str, Any]]). If you provide a list[str] (list of inputs), a new input set will be created using these inputs. A similar behavior occurs when providing raw data (list[dict[str, Any]]). All the entries in the list of raw dicts will be collected to create a new input set. TYPE: Union[str, list[str], list[dict[str, Any]]]

Examples:

>>> from nextmv.cloud import ScenarioInput, ScenarioInputType
>>> # Using an existing input set
>>> input_set = ScenarioInput(
...     scenario_input_type=ScenarioInputType.INPUT_SET,
...     scenario_input_data="input-set-id-123"
... )
>>> # Using a list of inputs
>>> inputs = ScenarioInput(
...     scenario_input_type=ScenarioInputType.INPUT,
...     scenario_input_data=["input-id-1", "input-id-2"]
... )
>>> # Using raw data
>>> raw_data = ScenarioInput(
...     scenario_input_type=ScenarioInputType.NEW,
...     scenario_input_data=[{"id": 1, "value": "data1"}, {"id": 2, "value": "data2"}]
... )

scenario_input_data instance-attribute

scenario_input_data: Union[
    str, list[str], list[dict[str, Any]]
]

Input data for the scenario. This can be a single input set ID (str), a list of input IDs (list[str]), or raw data (list[dict[str, Any]]).

scenario_input_type instance-attribute

scenario_input_type: ScenarioInputType

Type of input for the scenario. This is used to determine how the input should be processed.

ScenarioInputType

Bases: str, Enum

Type of input for a scenario. This is used to determine how the input should be processed.

You can import the ScenarioInputType class directly from cloud:

from nextmv.cloud import ScenarioInputType

PARAMETER	DESCRIPTION
INPUT_SET	The data in the scenario is an input set. TYPE: str
INPUT	The data in the scenario is an input. TYPE: str
NEW	The data in the scenario is new data. TYPE: str

Examples:

>>> from nextmv.cloud import ScenarioInputType
>>> input_type = ScenarioInputType.INPUT_SET

INPUT class-attribute instance-attribute

INPUT = 'input'

The data in the scenario is an input.

INPUT_SET class-attribute instance-attribute

INPUT_SET = 'input_set'

The data in the scenario is an input set.

NEW class-attribute instance-attribute

NEW = 'new'

The data in the scenario is new data.