# Scenario
`iota.session.Scenario()`
**Description** Iota scenario object.
**Methods**
* [`get_dataset`](#get_dataset)
* [`get_datasets`](#get_datasets)
* [`add_dataset`](#add_dataset)
* [`import_dataset`](#import_dataset)
* [`exists_dem_dataset`](#exists_dem_dataset)
* [`get_dem_dataset`](#get_dem_dataset)
* [`get_cg_dataset`](#get_cg_dataset)
* [`exists_graph`](#exists_graph)
* [`get_graph`](#get_graph)
* [`get_graphs`](#get_graphs)
* [`add_graph`](#add_graph)
* [`add_file`](#add_file)
* [`get_file`](#get_file)
* [`get_files`](#get_files)
* [`get_mesh`](#get_mesh)
* [`get_meshes`](#get_meshes)
* [`add_mesh`](#add_mesh)
* [`get_script`](#get_script)
* [`get_scripts`](#get_scripts)
* [`add_script`](#add_script)
* [`add_video`](#add_video)
* [`add_screenshot`](#add_screenshot)
* [`delete`](#delete)
* [`get_coarse_graining_settings`](#get_coarse_graining_settings)
* [`run_coarse_graining`](#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\])](#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()](#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\])](#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\])](#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()](#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()](#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()](#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\])](#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\])](#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()](#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\])](#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()](#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()](#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\])](#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)](#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()](#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\])](#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)](#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()](#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()](#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\])](#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\])](#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()](#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()](#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\])](#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)
```