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 |
|
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 |
|
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 |
|
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 |
|
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 Task
s. 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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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.