# Datasets

`iota.Dataset()`

**Description**

Iota Dataset object.

**Methods**

* [`__init__`](#dataset_ctor)
* [`name`](#dataset_name)
* [`software`](#dataset_software)
* [`type`](#dataset_type)
* [`reader_format`](#dataset_reader_format)
* [`timesteps`](#dataset_timesteps)
* [`timestep_exists`](#dataset_timestep_exists)
* [`timestep_count`](#dataset_timesteps_count)
* [`result_max`](#dataset_result_max)
* [`result_min`](#dataset_result_min)
* [`result_type`](#dataset_result_type)
* [`results`](#dataset_results)
* [`results_count`](#dataset_results_count)
* [`result_exists`](#dataset_result_exists)
* [`get_result_component`](#dataset_get_result_component)
* [`get_result_min`](#dataset_get_result_min)
* [`get_result_max`](#dataset_get_result_max)
* [`get_result_component_minmax`](#dataset_get_result_component_minmax)
* [`get_result_info`](#dataset_get_result_info)
* [`get_result_interpreter`](#dataset_get_result_interpreter)
* [`get_result_legend`](#dataset_get_result_legend)
* [`get_result_legends`](#dataset_get_result_legends)
* [`get_result_type`](#dataset_get_result_type)
* [`get_result`](#dataset_get_result)
* [`mesh_type`](#dataset_mesh_type)
* [`meshes`](#dataset_meshes)
* [`get_mesh`](#dataset_get_mesh)
* [`get_mesh_vertices`](#dataset_get_mesh_vertices)
* [`get_mesh_info`](#dataset_get_mesh_info)
* [`get_particles_mesh`](#dataset_get_particles_mesh)
* [`point_evolution`](#dataset_point_evolution)
* [`statistics_evolution`](#dataset_statistics_evolution)
* [`line_variation`](#dataset_line_variation)
* [`mesh_integral`](#dataset_mesh_integral)
* [`set_name`](#dataset_set_name)
* [`add_dem_mesh`](#dataset_add_dem_mesh)
* [`add_mesh`](#dataset_add_mesh)
* [`add_result`](#dataset_add_result)
* [`add_slice`](#dataset_add_slice)
* [`add_timestep`](#dataset_add_timestep)
* [`delete_mesh`](#dataset_delete_mesh)
* [`delete_mesh_finished`](#dataset_delete_mesh_finished)

## Methods

### [\_\_init\_\_(filename, \[mode\])](#dataset_ctor) <a href="#dataset_ctor" id="dataset_ctor"></a>

_Dataset constructor_

**Arguments**

* `filename`: (str) file path of the dataset (extension **.meta** required)
* `mode`: (IO\_Type) access mode: _WRITE_ or _READ\_ONLY_. (Default: **iota.IO\_Type.WRITE**)

**Example**

```python
my_dataset = iota.Dataset(
    filename = 'C:\Users\particle\Desktop\my_new_dataset.meta',
    mode = iota.IO_Type.WRITE
)
```

### [name()](#dataset_name) <a href="#dataset_name" id="dataset_name"></a>

_Get dataset name_ _Return the name as a **string**_

**Example**

```python
name = my_dataset.name()
print(name)
```

### [software()](#dataset_software) <a href="#dataset_software" id="dataset_software"></a>

_Get dataset software_

**Example**

```python
dataset_software = my_dataset.software()
print(dataset_software)
```

### [type()](#dataset_type) <a href="#dataset_type" id="dataset_type"></a>

_Get dataset type_ _Returns a value of type **iota.DatasetType**_

**Example**

```python
dataset_type = my_dataset.type()
print(dataset_type)
```

### [reader\_format()](#dataset_reader_format) <a href="#dataset_reader_format" id="dataset_reader_format"></a>

_Get dataset reader format_ _Returns the internal reader format as **string**_

**Example**

```python
dataset_reader_format = my_dataset.reader_format()
print(dataset_reader_format)
```

### [timesteps()](#dataset_timesteps) <a href="#dataset_timesteps" id="dataset_timesteps"></a>

_Get the list of timesteps_ _Returns a **list of string** that contains the timesteps of the dataset_

**Example**

```python
dataset_timesteps = my_dataset.timesteps()
print(dataset_timesteps)
```

### [timestep\_exists(timestep, mesh)](#dataset_timestep_exists) <a href="#dataset_timestep_exists" id="dataset_timestep_exists"></a>

_Checks for the existsence of a timestep on a given mesh_ _Returns a **boolean** value **True** if timestep exists, or **False** otherwise_

**Arguments**

* `timestep` : (int) timestep index to be checked
* `mesh` : (str) name of the mesh to be checked

**Example**

```python
mesh_exists_at_timestep = my_dataset.timestep_exists(0,'my_mesh')
print(mesh_exists_at_timestep)
```

### [timesteps\_count(mesh)](#dataset_timesteps_count) <a href="#dataset_timesteps_count" id="dataset_timesteps_count"></a>

_Get the number of timesteps for a given mesh_ _Returns the number of timesteps as an **integer**_

**Arguments**

* `mesh` : (str) name of the mesh

**Example**

```python
Number_timesteps_for_mesh = my_dataset.timesteps_count('my_mesh')
print(Number_timesteps_for_mesh)
```

### [result\_max(result, analysis)](#dataset_result_max) <a href="#dataset_result_max" id="dataset_result_max"></a>

_Get maximum global value for pair (result,analysis) for the whole simulation dataset_ _Returns a value of type equal to the result type_

**Arguments**

* `result` : (str) name of the result
* `analysis` : (str) name of the analysis

**Example**

```python
result_max = my_dataset.result_max('Density','none')
print(result_max)
```

### [result\_min(result, analysis)](#dataset_result_min) <a href="#dataset_result_min" id="dataset_result_min"></a>

_Get minimum global value for pair (result,analysis) for the whole simulation dataset_ _Returns a value of type equal to the result type_

**Arguments**

* `result` : (str) name of the result
* `analysis` : (str) name of the analysis

**Example**

```python
result_min = my_dataset.result_min('Density','none')
print(result_min)
```

### [result\_type(result, analysis)](#dataset_result_type) <a href="#dataset_result_type" id="dataset_result_type"></a>

_Get type of the result pair (result,analysis)_ _Returns a value of type **iota.ResultType** representing the type_

**Arguments**

* `result` : (str) name of the result
* `analysis` : (str) name of the analysis

**Example**

```python
result_type = my_dataset.result_max('Density','none')
print(result_type)
```

### [results(\[mesh\])](#dataset_results) <a href="#dataset_results" id="dataset_results"></a>

_Get the list of all results in the dataset for all the meshes, or for a specific mesh_ _Returns a **list of strings** if no mesh defined, of a **list of (string,string)** pairs with result name and analysis if a mesh is defined_

**Arguments**

* `mesh` : (str) name of the mesh (Default: **None**)&#x20;

**Example**

```python
results_list = my_dataset.results()
print(results_list)

result_list_mesh = my_dataset.results('my_mesh')
print(results_list_mesh)
```

### [results\_count(mesh)](#dataset_results_count) <a href="#dataset_results_count" id="dataset_results_count"></a>

_Get the number of results for for a specific mesh_ _Returns an **integer** that corresponds to the number of results for the specified mesh_

**Arguments**

* `mesh` : (str) name of the mesh

**Example**

```python
Number_results_mesh = my_dataset.results_count('my_mesh')
print(Number_results_mesh)
```

### [result\_exists(step, mesh, result, analysis)](#dataset_result_exists) <a href="#dataset_result_exists" id="dataset_result_exists"></a>

_Check for the existence of a result on a given timestep and mesh_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_exists = my_dataset(0,'my_mesh','Density','none')
print(result_exists)
```

### [get\_result\_component(step, mesh, result, analysis, component)](#dataset_get_result_component) <a href="#dataset_get_result_component" id="dataset_get_result_component"></a>

_Get a list of values per vertex/particle of a specific result,analysis and component_ _Returns a value of type **iota.ArrayXX** representing the values of result component. If component is **iota.ALL\_COMPONENTS**, all components of the result are returned. Otherwise, an **iota.ArrayFloat** is returned_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_component_values = my_dataset.get_result_component(1,'my_mesh','Velocity','none',2)
print(result_component_values)
```

### [get\_result\_min(step,mesh,result,analysis)](#dataset_get_result_min) <a href="#dataset_get_result_min" id="dataset_get_result_min"></a>

_Get minimum result value for a given step, mesh, result and analysis_ _Returns a value of type equal to the result_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_min_value = my_dataset.get_result_min(1,'my_mesh','Velocity','none')
print(result_min_value)
```

### [get\_result\_max(step,mesh,result,analysis)](#dataset_get_result_max) <a href="#dataset_get_result_max" id="dataset_get_result_max"></a>

_Get maximum result value for a given step, mesh, result and analysis_ _Returns a value of type equal to the result type_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_max_value = my_dataset.get_result_max(1,'my_mesh','Velocity','none')
print(result_max_value)
```

### [get\_result\_component\_minmax(step,mesh,result,analysis,component)](#dataset_get_result_component_minmax) <a href="#dataset_get_result_component_minmax" id="dataset_get_result_component_minmax"></a>

_Get a result array for a given step, mesh ad result/analysis, including min and max values_ _Returns a tuple (**iota.ArrayXX**, **min\_value**, **max\_value**), where XX is a **Float** or **Int** depending on the result type_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index

**Example**

```python
result_min_max = my_dataset.get_result_component_minmax(1,'my_mesh','Velocity','none',2)
print(result_min_max)
```

### [get\_result\_info(result,analysis)](#dataset_get_result_info) <a href="#dataset_get_result_info" id="dataset_get_result_info"></a>

_Get information of a given result_ _Returns a dictionary containing: type, name, analysis and list of meshes_

**Arguments**

* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_info = my_dataset.result_info('Velocity','none')
print(result_info)
```

### [get\_result\_interpreter(result,analysis)](#dataset_get_result_interpreter) <a href="#dataset_get_result_interpreter" id="dataset_get_result_interpreter"></a>

_Get the list of component labels for a given result/analysis_

* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_interpreter = my_dataset.result_interpreter('Velocity','none')
print(result_interpreter)
```

### [get\_result\_legend(result,analysis,component)](#dataset_get_result_legend) <a href="#dataset_get_result_legend" id="dataset_get_result_legend"></a>

_Get the legend of the result as shown in the colorbar of result screenshot/animation_ _Returns the string used as label for a given result/analysis, including result name, component and units (if available). If component is **iota.ALL\_COMPONENTS**, a list with legend for each component is returned_

* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index

**Example**

```python
result_legend = my_dataset.result_legend('Velocity','none',0)
print(result_legend)
```

### [get\_result\_legends(result,analysis)](#dataset_get_result_legends) <a href="#dataset_get_result_legends" id="dataset_get_result_legends"></a>

_Get list of result legends to shown in graph/animation for a given result/analysis_ _Returns a list of strings representing the labels per component. Equivalent to_ [_**get\_result\_legend(result,name,iota.ALL\_COMPONENTS)**_](#dataset_get_result_legend)

* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_legends = my_dataset.result_legends('Velocity','none')
print(result_legends)
```

### [get\_result\_type(result,analysis)](#dataset_get_result_type) <a href="#dataset_get_result_type" id="dataset_get_result_type"></a>

_Get result type_ _Returns a variable of type **iota.ResultType**_&#x20;

* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_type = my_dataset.get_result_type('Velocity','none')
print(result_type)
```

### [get\_result(step,mesh,result,analysis)](#dataset_get_result) <a href="#dataset_get_result" id="dataset_get_result"></a>

_Get values of a result for a given step, mesh, result and analysis_ _Returns an **iota.ArrayXX** where XX is a **Float** or **Int** depending on the result type_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name

**Example**

```python
result_values = my_dataset.get_result(5,'my_mesh','Velocity','none')
```

### [mesh\_type(mesh)](#dataset_mesh_type) <a href="#dataset_mesh_type" id="dataset_mesh_type"></a>

_Get type of a mesh in the dataset_ _Returns a variable of type **iota.MeshType**_

**Arguments**

* `mesh` : (str) mesh name

**Example**

```python
mesh_type = my_dataset.mesh_type('my_mesh')
print(mesh_type)
```

### [meshes()](#dataset_meshes) <a href="#dataset_meshes" id="dataset_meshes"></a>

_Get the list of meshes in the dataset_ _Returns a list of strings representing the name of the meshes_

**Example**

```python
meshes_name = my_dataset.meshes()
print(meshes_name)
```

### [get\_mesh(mesh,step)](#dataset_get_mesh) <a href="#dataset_get_mesh" id="dataset_get_mesh"></a>

_Get a mesh for a given step in the dataset_ _Returns a variable of type **iota.mesh.Mesh**_

**Arguments**

* `mesh` : (str) mesh name
* `step` : (int) timestep index

**Example**

```python
mesh = my_dataset.get_mesh('my_mesh',0)
print(mesh)
```

### [get\_mesh\_vertices(mesh,step)](#dataset_get_mesh_vertices) <a href="#dataset_get_mesh_vertices" id="dataset_get_mesh_vertices"></a>

_Get the vertices of a mesh vertices for a given step in the dataset_ _Returns an array containing the position of each vertex in the mesh_

**Arguments**

* `mesh` : (str) mesh name
* `step` : (int) timestep index

**Example**

```python
mesh_vertices = my_dataset.get_mesh_vertices('my_mesh',0)
print(mesh_vertices)
```

### [get\_mesh\_info(mesh)](#dataset_get_mesh_info) <a href="#dataset_get_mesh_info" id="dataset_get_mesh_info"></a>

_Get the information on a specific mesh_ _Returns a dictionary containing the variables **name**, **type** and **dynamic**_

**Arguments**

* `mesh` : (str) mesh name

**Example**

```python
mesh_info = my_dataset.get_mesh_info('my_mesh')
print(mesh_info)
```

### [get\_particles\_mesh(step,mesh,variable)](#dataset_get_particles_mesh) <a href="#dataset_get_particles_mesh" id="dataset_get_particles_mesh"></a>

_Get the value of an attribute/variable for a given step and particle mesh_ _Returns an array of values representing for the given attribute/variable: **position**, **orientation**, **type**, **group**, **labels** or **spheres**_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) particles mesh name
* `variable` : (str) attribute name: **position**, **orientation**, **type**, **group**, **labels** or **spheres**

**Example**

```python
particle_mesh_variable = my_dataset.get_particles_mesh(3,'my_particles_mesh','position')
```

### [point\_evolution(mesh,point,result,analysis,component,\[step\])](#dataset_point_evolution) <a href="#dataset_point_evolution" id="dataset_point_evolution"></a>

_Get the value of a result/analysis in a given point for one or all timesteps_ _Returns a pair (**iota.ArrayFloat**,**list\[iota.ArrayFloat]**),where the first element is the array of values representing the timesteps and the second one is the list of result arrays per component_

**Arguments**

* `mesh` : (str) mesh name
* `point` : (iota.Vector3d) point to evaluate the result
* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index
* `step` : (int) timestep index (Default: **iota.ALL\_STEPS**)

**Example**

```python
x, y = my_dataset.statistics_evolution('my_mesh',iota.Vector3d(0,0.1,0.5),'Velocity','none',3,step=iota.ALL_STEPS)
print(x)
print(y)
```

### [statistics\_evolution(mesh,result,analysis,component,\[step\],\[data\])](#dataset_statistics_evolution) <a href="#dataset_statistics_evolution" id="dataset_statistics_evolution"></a>

_Get the evolution of different statistical variables for a given mesh/result/analsys_ _Returns a pair (**iota.ArrayFloat**,**list\[iota.ArrayFloat]**),where the first element is the array of values representing the timesteps and the second one is the list of result arrays per variable_

**Arguments**

* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index
* `step` : (int) timestep index (Default: **iota.ALL\_STEPS**)
* `data` : (list\[str]) list of statistical values to be evaluated: **min**, **max**, **mean**, **stdev**, **median**, **cov** (Default: **\[]**)

**Example**

```python
x, y = my_dataset.statistics_evolution('my_mesh','Velocity','none',3,step=iota.ALL_STEPS,data=['min','max', 'mean'])
print(x)
print(y)
```

### [line\_variation(mesh,point\_start,point\_end,num\_points,result,analysis,component,step,\[x\_type\])](#dataset_line_variation) <a href="#dataset_line_variation" id="dataset_line_variation"></a>

_Get the results evaluated in a give line through a mesh_ _Returns a pair (**iota.ArrayFloat**,**list\[iota.ArrayFloat]**),where the first element is the array of values representing the point/positions in the line and the second one is the list of result arrays per component_

**Arguments**

* `mesh` : (str) mesh name
* `point_start` : (iota.Vector3d) point representing the start of the line
* `point_end` : (iota.Vector3d) point representing the end of the line
* `num_points` : (int) number of points in the line to evaluate the result
* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index
* `step` : (int) timestep index
* `x_type` : (str) variable to be used in the x axis of the graph: **'x'**, **'y'**, **'z'**, **'dist'** (Default: **'dist'**)

**Example**

```python
x, y = my_dataset.line_variation('my_mesh',iota.Vector3d(0,0,0),iota.Vector3d(0,0,2.5),50,'Velocity','none',3,5,'z')
print(x)
print(y)
```

### [mesh\_integral(mesh,result,analysis,component,\[step\])](#dataset_mesh_integral) <a href="#dataset_mesh_integral" id="dataset_mesh_integral"></a>

_Get the volume/area integral of a result/analysis over a given mesh_ _Returns a pair (**iota.ArrayFloat**,**list\[iota.ArrayFloat]**),where the first element is the array of values representing the timesteps and the second one is the list of result arrays per component_

**Arguments**

* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name
* `component` : (int) component index
* `step` : (int) timestep index (Default: **iota.ALL\_STEPS**)

**Example**

```python
x, y = my_dataset.mesh_integral('my_mesh','Velocity','none',3,step=5)
print(x)
print(y)
```

### [set\_name(name)](#dataset_set_name) <a href="#dataset_set_name" id="dataset_set_name"></a>

_Sets the name of the dataset_

**Arguments**

* `name` : (str) new name of the dataset

**Example**

```python
my_dataset.set_name('new name')
print(my_dataset.name())
```

### [add\_dem\_mesh(step,mesh,\[name\])](#dataset_add_dem_mesh) <a href="#dataset_add_dem_mesh" id="dataset_add_dem_mesh"></a>

_Adds a mesh of particles (DEM) to a existing step in the dataset_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (iota.mesh.DEM\_Mesh) particle (DEM) mesh class
* `name` : (str) mesh name (Default: **'particles'**)

**Example**

```python
my_dataset.add_dem_mesh(0,my_DEM_particles_mesh)
```

### [add\_mesh(step,mesh)](#dataset_add_mesh) <a href="#dataset_add_mesh" id="dataset_add_mesh"></a>

_Adds a mesh to a existing step in the dataset_

**Arguments**

* `step` : (int) timestep index or **iota.STATIC\_MESH** if the mesh to be added is static
* `mesh` : (iota.mesh.Mesh) mesh to be added to the dataset

**Examples**

```python
my_dataset.add_mesh(5, my_mesh)
```

```python
my_dataset.add_mesh(iota.STATIC_MESH, my_static_mesh)
```

### [add\_result(step,mesh,result,analsis,data)](#dataset_add_result) <a href="#dataset_add_result" id="dataset_add_result"></a>

_Adds a result to a existing mesh and step in the dataset_

**Arguments**

* `step` : (int) timestep index
* `mesh` : (str) mesh name
* `result` : (str) result name
* `analysis` : (str) analysis name
* `data` : (iota.ArrayXX) array of results to be added to dataset

**Example**

```python
my_dataset.add_result(5,'my_mesh','my_new_result','none', my_new_result_data)
```

### [add\_slice()](#dataset_add_slice) <a href="#dataset_add_slice" id="dataset_add_slice"></a>

_Creates a mesh slice/cut-plane defined by a pair of vectors (origin,normal) representing the plane and it is added to the dataset as new mesh_

**Arguments**

* `mesh` : (str) name of the mesh to be cut
* `normal` : (iota.Vector3d) vector representing the normal direction to define the slice/cut-plane&#x20;
* `origin` : (iota.Vector3d) vector contained in the slice/cut-plane plane
* `result` : (str) name of an existing result in the dataset to be interpolated on the slice/cut-plane. If empty, all results in the dataset are included (Default: '')
* `analysis` : (str) name of the analysis of an existing result in the dataset. If empty, all analysis are included (Default: '')
* `step` : (int) timestep index (Default: **iota.ALL\_STEPS**)

**Examples**

```python
my_dataset.add_slice('my_mesh',iota.Vector3d(0,0,1), iota.Vector3d(0,0,0),'Velocity','none')
```

```python
my_dataset.add_slice('my_mesh',iota.Vector3d(0,0,1), iota.Vector3d(0,0,0),'Velocity','none', 3)
```

### [add\_timestep(timestep)](#dataset_add_timestep) <a href="#dataset_add_timestep" id="dataset_add_timestep"></a>

_Adds a new timestep to the dataset_

**Arguments**

* `timestep` : (str) timestep to be added

**Example**

```python
my_dataset.add_timestep('15.65')
print(my_dataset.timesteps())
```

### [delete\_mesh(mesh)](#dataset_delete_mesh) <a href="#dataset_delete_mesh" id="dataset_delete_mesh"></a>

_Deletes a mesh from the dataset_

**Arguments**

* `mesh` : (str) mesh name

**Example**

```python
my_dataset.delete_mesh('my_mesh')
```

### [delete\_mesh\_finished()](#dataset_delete_mesh_finished) <a href="#dataset_delete_mesh_finished" id="dataset_delete_mesh_finished"></a>

_Check of a mesh deletion process have finished_ _Returns a pair (bool,str) with the status of the process. If process finished correctly, the boolean is True and message empty. In case of error, the error message is added as the second element of the pair_

**Example**

```python
status, msg = my_dataset.delete_mesh_finished()
print(status, msg)
```
