Skip to content

Scenario and cycle management

The previous section provided documentation on Scenario creation. Now that we know how to create a new Scenario, this section will describe the scenario's attributes and the various utility methods.

In this section, it is assumed that the my_config.py module contains a Taipy configuration already implemented.

Scenario attributes

The scenario creation method returns a Scenario entity. It is identified by a unique identifier id that was generated by Taipy. A scenario also holds various properties, each accessible as an attribute of the scenario:

  • config_id is the id of the scenario configuration.
  • creation_date corresponds to the date-time provided at the creation.
  • is_primary is True if it is a primary scenario. False otherwise.
  • subscribers is the list of Tuple(callbacks, params) representing the subscribers.
  • version: The string indicates the application version of the scenario to instantiate. If not provided, the current version is used. Refer to the version management page for more details.
  • properties is the complete dictionary of the scenario properties. It includes a copy of the properties of the scenario configuration, in addition to the properties provided at the creation and at runtime.
  • cycle is the cycle of the scenario.
  • tasks is a dictionary holding the various tasks of the scenario. The key corresponds to the task's config_id (while the value is the task itself).
  • additional_data_nodes is a dictionary holding the various additional data nodes of the scenario. The key corresponds to the data node's config_id (while the value is the data node itself).
  • data_nodes is a dictionary holding all data nodes of the scenario including those in the executable graph and the additional data nodes that are not part of the executable graph. The key corresponds to the data node's config_id (while the value is the data node itself).
  • sequences is a dictionary holding the various sequences of the scenario. The key corresponds to the sequence's config_id (while the value is the sequence itself).
  • tag is the tag used to search among the set of scenario's tags.
  • owner_id is the identifier of the owner, which is the cycle of the scenario.
  • name is the name of the scenario.
  • Each property of the properties dictionary is also directly exposed as an attribute.
  • Each nested entity is also exposed as an attribute of the scenario. The attribute name corresponds to the config_id of the nested entity.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import taipy as tp
from datetime import datetime
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg,
                              creation_date=datetime(2022, 1, 1),
                              name="Scenario for January")

# The config_name is an attribute of the scenario and equals "scenario_configuration"
scenario.config_name
# The creation date is the date-time provided at the creation. It equals datetime(2022, 1, 1)
scenario.creation_date
# The is_primary property equals `True` since it is the only scenario of the cycle.
scenario.is_primary
# There was no subscription, so subscribers is an empty list
scenario.subscribers # []
# The properties' dictionary equals {"name": "Scenario for January"}. It contains all the properties,
# including the `name` provided at the creation
scenario.properties # {"name": "Scenario for January"}
# The `name` property is also exposed directly as an attribute. It equals "Scenario for January"
scenario.name
# the sales sequence entity is exposed as an attribute of the scenario
sales_sequence = scenario.sales
# the production sequence entity as well
production_sequence = scenario.production
# All the tasks are also exposed as attributes, including the training task entity
training_task = scenario.training
# The six data nodes are also exposed as attributes of the scenario.
current_month_data_node = scenario.current_month

Taipy exposes multiple methods to manage the various scenarios.

Get a scenario by id

The first method to get a scenario is from its id by using the taipy.get() method:

1
2
3
4
5
6
import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
scenario_retrieved = tp.get(scenario.id)
scenario == scenario_retrieved

Here, the two variables scenario and scenario_retrieved are equal.

Get scenarios by config id

Scenarios can also be retrieved using taipy.get_entities_by_config_id() providing the config_id. This method returns the list of all existing scenarios instantiated from the config_id provided as a parameter.

Example

1
2
3
4
5
6
7
8
9
import taipy as tp
import my_config

# Create 2 scenarios.
scenario_1 = tp.create_scenario(my_config.monthly_scenario_cfg)
scenario_2 = tp.create_scenario(my_config.monthly_scenario_cfg)

# Get all monthly scenarios by config id, this will return a list of 2 scenarios just created.
all_monthly_scenarios = tp.get_entities_by_config_id("scenario_configuration")

Get all scenarios

All the scenarios can be retrieved using the method taipy.get_scenarios(). This method returns the list of all existing scenarios. If an optional cycle is given as a parameter, the list contains all the existing scenarios of the cycle. If an optional tag is provided as a parameter, the list contains all the existing scenarios tagged with the tag provided.

Get all scenarios grouped by cycles

All scenarios can be retrieved and grouped by their cycles by calling taipy.get_cycles_scenarios(). This method returns a dictionary with cycles as keys and lists of corresponding scenarios as values.

Get primary scenarios

The taipy.get_primary() method returns the primary scenario of the cycle given as a parameter.

taipy.get_primary_scenarios() returns the primary scenarios for all the existing cycles.

Promote a scenario as primary

To set a scenario as primary, the taipy.set_primary() method must be used. It promotes the scenario given as a parameter to the primary scenario of its cycle. If the cycle already had a primary scenario it will be demoted: It will no longer be primary for the cycle.

Delete a scenario

A scenario can be deleted by using taipy.delete() which takes the scenario id as a parameter. The deletion is also propagated to the nested sequences, tasks, data nodes, and jobs if they are not shared with any other scenarios.

If there is more than one scenario in the cycle, an error will be raised if you try to delete a primary scenario. You must promote another scenario as primary before deleting the primary one. On the other hand, if there is only one scenario in the cycle, the primary scenario can be deleted, which will also delete its cycle.

Compare scenarios

You can compare two or more scenarios, created from the same scenario configuration, by using taipy.compare_scenarios(). This function accepts two or more scenarios to be compared, you can also provide the data node config id to specify which data nodes from the scenarios you want to compare.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import taipy as tp
from datetime import datetime
from my_config import *

tp.Core().run()

previous_month_scenario = tp.create_scenario(monthly_scenario_cfg)
previous_month_scenario.current_month.write(datetime(2020, 1, 1))
previous_month_scenario.submit()

current_month_scenario = tp.create_scenario(monthly_scenario_cfg)
current_month_scenario.current_month.write(datetime(2020, 2, 1))
current_month_scenario.submit()

tp.compare_scenarios(previous_month_scenario,
           current_month_scenario,
           data_node_config_id="sales_predictions")

Note

To specify how to compare scenarios on data nodes, you need to define comparison functions. Please refer to the Scenario Config page.

Add or remove sequences

A scenario can have multiple sequences. You can add a sequence or sequences to a scenario calling Scenario.add_sequences() and provide it with a dictionary with the key being the sequence name and the value is a list of Tasks. In contrast, you can also remove a sequence or sequences from a scenario using Scenario.remove_sequences() and provide the function with a sequence name or a list of sequence names.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import taipy as tp
from my_config import *

scenario = tp.create_scenario(monthly_scenario_cfg)
tasks = scenario.tasks
training_task, predicting_task, planning_task = tasks["training_cfg"], tasks["predicting_cfg"], tasks["planning_cfg"]
scenario.add_sequences({"sales": [training_task, predicting_task], "production": [planning_task]})

# and you can remove sequence
scenario.remove_sequences("sales")
# or
scenario.remove_sequences(["sales", "production"])

Tag or untag a scenario

A scenario can have multiple tags. You can add a tag to a scenario using taipy.tag(). Alternatively, you can use the Scenario.add_tag() method.

1
2
3
4
5
6
7
import taipy as tp
from my_config import *

scenario = tp.create_scenario(monthly_scenario_cfg)
tp.tag(scenario, "my_tag")
# or
scenario.add_tag("my_tag")

You can retrieve all scenarios that have a specific tag using taipy.get_scenarios() with the tag parameter.

Two scenarios belonging to the same cycle can not have the same tag. If a tag is already used by an existing scenario from the same cycle, it will be removed from that scenario and reassigned to the new scenario.

You can remove a tag of a scenario using taipy.untag(). Alternatively, you can use the Scenario.remove_tag() method.

1
2
3
4
5
6
7
import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
tp.untag(scenario, "my_tag")
# or
scenario.remove_tag("my_tag")

You can define a list of authorized tags in the scenario configuration by specifying the value of authorized_tags. From the scenarios that are created from that configuration, if you add a tag that is not authorized, an exception will be raised.

Export a scenario

You can export a scenario with its related entities in JSON format into a folder using taipy.export_scenario(). This method takes as parameters the scenario id and the path to the export folder.

Warning

The folder_path will be overwritten if it does exist.

Alternatively, you can use the Scenario.export() method.

1
2
3
4
5
6
7
8
import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)

tp.export(scenario.id, folder_path="./monthly_scenario")
# or
scenario.export(folder_path="./monthly_scenario")

Cycle attributes

As we saw in the previous chapter, the Cycle creation is indirectly triggered by the scenario creation method. A cycle is identified by a unique identifier id that was generated by Taipy. A cycle also holds various attributes and properties, each accessible as an attribute of the cycle:

  • frequency corresponds to the cycle Frequency. It is populated at the cycle creation using the scenario frequency that triggered the cycle creation.
  • creation_date corresponds to the date-time of the creation of this cycle.
  • start_date corresponds to the date and time of the start of this cycle.
  • end_date corresponds to the date and time of the end of this cycle.
  • name corresponds to a user readable name of this cycle.
  • Each property of the properties' dictionary is also directly exposed as an attribute.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import taipy as tp
from datetime import datetime
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg,
                              creation_date=datetime(2022, 1, 3))
cycle = scenario.cycle

# The frequency is an attribute of the cycle. In the example, it equals
# Frequency.MONTHLY since my_config.monthly_scenario_cfg is used has been
# used to instantiate scenario and cycle.
cycle.frequency
# The creation date is the date-time provided at the creation. It equals datetime(2022, 1, 3)
cycle.creation_date
# The start date is the date-time of the start of the cycle. It equals datetime(2022, 1, 1)
cycle.start_date
# The end date is the date-time of the end of the cycle. It equals datetime(2022, 1, 31)
cycle.end_date
# By default, the `name` is generated. It can be set manually.
cycle.name = "January cycle"

Get a cycle by id

The basic method to get a cycle is from its id by using the taipy.get() method:

1
2
3
4
5
6
7
import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
cycle = scenario.cycle
cycle_retrieved = tp.get(cycle.id)
cycle == cycle_retrieved

Here, the two variables cycle and cycle_retrieved are equal.

Get all cycles

All the cycles can be retrieved using the method taipy.get_cycles(). This method returns the list of all existing cycles.

Delete a cycle

A cycle can be deleted by using taipy.delete() which takes the cycle id as a parameter. The deletion is also propagated to the nested scenarios, sequences, tasks, data nodes, and jobs if they are not shared with any other cycles.

The next section presents the sequence management.