# Scenario
`iota.session.Scenario()`
**Description** Iota scenario object.
**Methods**
* [`get_dataset`](/iota-python-api/19.2.1/iota/scenario.md#get_dataset)
* [`get_datasets`](/iota-python-api/19.2.1/iota/scenario.md#get_datasets)
* [`add_dataset`](/iota-python-api/19.2.1/iota/scenario.md#add_dataset)
* [`import_dataset`](/iota-python-api/19.2.1/iota/scenario.md#import_dataset)
* [`exists_dem_dataset`](/iota-python-api/19.2.1/iota/scenario.md#exists_dem_dataset)
* [`get_dem_dataset`](/iota-python-api/19.2.1/iota/scenario.md#get_dem_dataset)
* [`get_cg_dataset`](/iota-python-api/19.2.1/iota/scenario.md#get_cg_dataset)
* [`exists_graph`](/iota-python-api/19.2.1/iota/scenario.md#exists_graph)
* [`get_graph`](/iota-python-api/19.2.1/iota/scenario.md#get_graph)
* [`get_graphs`](/iota-python-api/19.2.1/iota/scenario.md#get_graphs)
* [`add_graph`](/iota-python-api/19.2.1/iota/scenario.md#add_graph)
* [`add_file`](/iota-python-api/19.2.1/iota/scenario.md#add_file)
* [`get_file`](/iota-python-api/19.2.1/iota/scenario.md#get_file)
* [`get_files`](/iota-python-api/19.2.1/iota/scenario.md#get_files)
* [`get_mesh`](/iota-python-api/19.2.1/iota/scenario.md#get_mesh)
* [`get_meshes`](/iota-python-api/19.2.1/iota/scenario.md#get_meshes)
* [`add_mesh`](/iota-python-api/19.2.1/iota/scenario.md#add_mesh)
* [`get_script`](/iota-python-api/19.2.1/iota/scenario.md#get_script)
* [`get_scripts`](/iota-python-api/19.2.1/iota/scenario.md#get_scripts)
* [`add_script`](/iota-python-api/19.2.1/iota/scenario.md#add_script)
* [`add_video`](/iota-python-api/19.2.1/iota/scenario.md#add_video)
* [`add_screenshot`](/iota-python-api/19.2.1/iota/scenario.md#add_screenshot)
* [`delete`](/iota-python-api/19.2.1/iota/scenario.md#delete)
* [`get_coarse_graining_settings`](/iota-python-api/19.2.1/iota/scenario.md#get_coarse_graining_settings)
* [`run_coarse_graining`](/iota-python-api/19.2.1/iota/scenario.md#run_coarse_graining)
**Variables**
* `name` (str) scenario name
* `description` (str) scenario description
* `id` (int) scenario Id
* `project` (iota.session.Project) the project containing this scenario
## Methods
### [get\_dataset(name,\[data\_format\])](/iota-python-api/19.2.1/iota/scenario.md#get_dataset)
*Return a dataset record specified by name*
**Arguments**
* `name`: (str) dataset name
* `data_format`: (str) data format of the dataset to be loaded. The scenario can have more than one dataset with the same name if data\_format is different. (default: **None**)
**Example**
```python
dataset = my_scenario.get_dataset(
name = 'mixing_rpm_30',
data_format = 'PADEM'
)
```
### [get\_datasets()](/iota-python-api/19.2.1/iota/scenario.md#get_datasets)
*Return the list of dataset records in the scenario*
**Example**
```python
print('List of datasets in the scenario')
for dataset in my_scenario.get_datasets():
print('dataset: {} (format: {})'.format(dataset.name,dataset.data_format))
```
### [add\_dataset(name, data\_format, file, \[description\])](/iota-python-api/19.2.1/iota/scenario.md#add_dataset)
*Add a Iota Dataset file to a scenario* *data\_format must be one of **PADEM** or **PACG***
**Arguments**
* `name`: (str) dataset name
* `data_format`: (str) format of the dataset
* `file`: (str) dataset filepath
* `description`: (str) dataset description (default: **None**)
**Example**
```python
my_scenario.add_dataset(
name = 'mixing_rpm_32',
data_format = 'PADEM',
file = '/path/to/my/dataset/mixing_rpm_32.meta',
description = 'mixing analysis with drum speed of 32 RPM'
)
```
### [import\_dataset(file,\[name\],\[data\_format\],\[include\_graphs\],\[description\])](/iota-python-api/19.2.1/iota/scenario.md#import_dataset)
*Import external Dataset to a scenario* *data\_format must be one of the accepted formats: \[**EDEM 2017**]*
**Arguments**
* `file`: (str) dataset filepath
* `name`: (str) dataset name. If not defined, used the basename of the filepath (Default: **None**)
* `data_format`: (str) format of the dataset
* `include_graphs`: (bool) import any graph available in the dataset to the scenario
* `description`: (str) dataset description (Default: **None**)
**Example**
```python
my_scenario.import_dataset(
file = '/path/to/my/edem/dataset/simulation.dem',
name = 'mixing_rpm_34',
data_format = 'EDEM 2017',
include_graphs = True,
description = 'mixing analysis with drum speed of 34 RPM'
)
```
### [exists\_dem\_dataset()](/iota-python-api/19.2.1/iota/scenario.md#exists_dem_dataset)
*Check if exists a DEM dataset in the scenario*
**Example**
```python
if my_scenario.exists_dem_dataset():
print('Scenario have a DEM dataset')
```
### [get\_dem\_dataset()](/iota-python-api/19.2.1/iota/scenario.md#get_dem_dataset)
*Return the scenario DEM Dataset if one exists in the scenario*
**Example**
```python
dataset = my_scenario.get_dem_dataset()
print('Dataset format: {}'.format(dataset.data_format))
```
### [get\_cg\_dataset()](/iota-python-api/19.2.1/iota/scenario.md#get_cg_dataset)
*Return the scenario CG Dataset if one exists in the scenario*
**Example**
```python
dataset = my_scenario.get_cg_dataset()
print('Dataset format: {}'.format(dataset.data_format))
```
### [exists\_graph(name,\[tags\])](/iota-python-api/19.2.1/iota/scenario.md#exists_graph)
*Return True if graph exists, specified by name (and tags)*
**Arguments**
* `name`: (str) graph name
* `tags`: (dict) tags dictionary
**Example**
```python
exists_graph = my_scenario.exists_graph(
name = 'Reaction Force',
tags = {
'dataset': 'mixing_rpm_34'
}
)
if exists_graph:
print('graph exist!')
```
### [get\_graph(name,\[tags\])](/iota-python-api/19.2.1/iota/scenario.md#get_graph)
*Return a graph, specified by name (and tags)*
**Arguments**
* `name`: (str) graph name
* `tags`: (dict) tags dictionary
**Example**
```python
graph = my_scenario.get_graph(
name = 'Reaction Force',
tags = {
'dataset': 'mixing_rpm_34'
}
)
```
### [get\_graphs()](/iota-python-api/19.2.1/iota/scenario.md#get_graphs)
*Return the list of graphs in the scenario*
**Example**
```python
print('List of graphs:')
for graph in my_scenario.get_graphs():
print('Graph: {}'.format(graph.name))
```
### [add\_graph(name,\[title\],\[xdata\],\[ydata\],\[legend\],\[xtitle\],\[ytitle\],\[csvfile\],\[overwrite\],\[description\],\[tags\])](/iota-python-api/19.2.1/iota/scenario.md#add_graph)
*Add a new graph to a scenario.* *The graph can be defined in a **csv file** or by defining all the components (data, titles, etc)*
**Arguments**
* `name`: (str) graph name
* `title`: (str) graph title
* `filepath`: (str) optional file path for new graph file (Default: **None**)
* `xdata`: (iota.ArrayFloat) array of data representing the values of axis X
* `ydata`: (list\[iota.ArrayFloat]) list of arrays representing the data series
* `legend`: (list\[str]) list of names for the data series
* `xtitle`: (str) title of the axis X
* `ytitle`: (str) title of the axis Y
* `csvfile`: (str) csv file containing the graph data. If this is defined, none of the previous variables are considered
* `description`: (str) graph description
* `tags`: (dict) tags dictionary
* `overwrite`: (bool) overwrite graph file if already exists
**Example**
```python
x_values = iota.ArrayFloat([0,1,2,3,4,5,6])
average_force = iota.ArrayFloat(len(x_values),10.0)
graph = my_scenario.add_graph(
name = 'Average Force',
title = 'Average Force',
xtitle = 'Step',
xdata = x_values,
ytitle = 'Force',
legend = ['Force'],
ydata = [average_force],
tags = {
'dataset': 'mixing_rpm_34'
},
overwrite = True
)
graph2 = my_scenario.add_graph(
name = 'Average Torque',
csvfile = '/path/to/my/graph/torque.csv',
tags = {
'dataset': 'mixing_rpm_34'
}
)
```
### [get\_mesh()](/iota-python-api/19.2.1/iota/scenario.md#get_mesh)
*Return a mesh specified by a name*
**Arguments**
* `name`: (str) mesh name
**Example**
```python
mesh_record = my_scenario.get_mesh(
name = 'mixing_drum_v02'
)
```
### [get\_meshes()](/iota-python-api/19.2.1/iota/scenario.md#get_meshes)
*Return th elist of meshes in a scenario*
**Example**
```python
print('List of meshes:')
for mesh in my_scenario.get_meshes():
print(' mesh: {}'.format(mesh.name))
```
### [add\_mesh(file, \[description\])](/iota-python-api/19.2.1/iota/scenario.md#add_mesh)
*Add a mesh by filepath to a scenario*
**Arguments**
* `file`: (str) mesh filepath
* `description`: (str) mesh description
**Example**
```python
my_scenario.add_mesh(
file = '/path/to/my/mesh/mixing_drum_v2.stl',
description = 'Mixing drum with inclinantion of 30 degrees'
)
```
### [get\_file(name)](/iota-python-api/19.2.1/iota/scenario.md#get_file)
*Return a file, specified by name*
**Arguments**
* `name`: (str) file name
**Example**
```python
file = my_scenario.get_file(
name = 'list of values test 2'
)
```
### [get\_files()](/iota-python-api/19.2.1/iota/scenario.md#get_files)
*Return the list of files in a scenario*
**Example**
```python
print('List of files:')
for file in my_scenario.get_files():
print(' file: {}'.format(file.name))
```
### [add\_file(name, filepath, \[description\])](/iota-python-api/19.2.1/iota/scenario.md#add_file)
*Create and return a file, describe by name, filepath and optional description*
**Arguments**
* `name`: (str) scenario name
* `filepath`: (str) file path
* `description`: (str) file description (Default: **None**)
**Example**
```python
my_scenario.add_file(
name = 'my text file',
filepath= '/path/to/my/file/text.txt',
description='this file contains the summary of parameters used for the simulations'
)
```
### [get\_script(name)](/iota-python-api/19.2.1/iota/scenario.md#get_script)
*Return a script spcified by a name*
**Arguments**
* `name`: (str) script name
**Example**
```python
script_file = my_scenario.get_script(
name = 'calculate mixing index'
)
```
### [get\_scripts()](/iota-python-api/19.2.1/iota/scenario.md#get_scripts)
*Return the list of scripts in a scenario*
**Example**
```python
print('List of scripts:')
for script in my_scenario.get_scripts():
print(' script: {}'.format(script.name))
```
### [add\_script()](/iota-python-api/19.2.1/iota/scenario.md#add_script)
*Add a script (python file) to a scenario*
**Arguments**
* `name`: (str) script name
* `filepath`: (str) script file path
* `description`: (str) script description (Default: **None**)
**Example**
```python
my_scenario.add_script(
name = 'calculate mixing index',
filepath = '/path/to/my/scripts/calculate_mixing_index.py',
description = 'This script calculate the Lacey mixing index using binning'
)
```
### [add\_video(file,name,\[description\],\[tags\],\[thumbnail\])](/iota-python-api/19.2.1/iota/scenario.md#add_video)
*Add a video file to a scenario*
**Arguments**
* `file`: (str) video file path
* `name`: (str) video name
* `description`: (str) video description (Default: **None**)
* `tags`: (dict) tags dictionary (Default: **None**)
* `thumbnail`: (str) image file to be used as a thumbnail (Default: **None**)
**Example**
```python
my_scenario.add_video(
file = '/path/to/my/videos/mixer_rpm_32_velocity_X.mp4',
name = 'Mixer at 32 RPM',
description = 'This video shows the velocity profile in X direction for the case with drum speed at 32 RPM',
tags = {
'dataset': 'mixer_rpm_32',
'result': 'Velocity (X)'
}
)
```
### [add\_screenshot(file,name,\[description\],\[tags\])](/iota-python-api/19.2.1/iota/scenario.md#add_screenshot)
*Add image file to a scenario*
**Arguments**
* `file`: (str) screenshot file path
* `name`: (str) screenshot name
* `description`: (str) screenshot description (Default: **None**)
* `tags`: (dict) tags dictionary (Default: **None**)
**Example**
```python
my_scenario.add_video(
file = '/path/to/my/images/mixer_rpm_32_velocity-Y_time3.42.png',
name = 'Mixer at 32 RPM',
description = 'Velocity profile in Y direction for the case with drum speed at 32 RPM. Time = 3.42s',
tags = {
'dataset': 'mixer_rpm_32',
'result': 'Velocity (Y)',
'timestep': '3.42'
}
)
```
### [delete()](/iota-python-api/19.2.1/iota/scenario.md#delete)
*Delete scenario from the database (and disk if applicable)*
**Example**
```python
name = my_scenario.name
my_scenario.delete()
if not my_project.exist_scenario(name):
print('scenario removed')
```
### [get\_coarse\_graining\_settings()](/iota-python-api/19.2.1/iota/scenario.md#get_coarse_graining_settings)
*Retun the a CG Settings object of defined in the current scenario (see* [*CG\_Settings*](https://github.com/particle-analytics/iota-python-api/tree/79ae110f50c92abf90b9e5d280ab032d313fe62c/cg_settings.md) *for more info)*
**Example**
```python
config = my_scenario.get_coarse_graining_settings()
print('CG Output name: {}'.format(config['output']['name']))
```
### [run\_coarse\_graining(\[with\_settings\], \[print\_messages\])](/iota-python-api/19.2.1/iota/scenario.md#run_coarse_graining)
*Run coarse graining on a scenario with optional custom settings.* *If custom settings are provided, a copy of the provided settings with with modified output directory and scenario fields will be used.*
**Arguments**
* `with_settings`: (iota.session.CG\_Settings) Alternative settings to replace local one used for the analysis (Default: **None**)
* `print_messages`: (bool) activate/deactivate full verbosity during execution (Default: **False**)
**Example**
```python
cg_settings = my_scenario.get_coarse_graining_settings()
cg_settings['output']['name'] = 'My dataset name'
cg_settings['output']['padem'] = True
cg_settings.set()
results = my_scenario.run_coarse_graining(
print_messages = True)
print(results.datasets)
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://particle-analytics-1.gitbook.io/iota-python-api/19.2.1/iota/scenario.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.