# iota.coarsegraining

**Description**

This module provides functionalities to transform the discrete data from particle based simulations (e.g DPM, DEM) into continuum data.

* [CoarseGraining](#class_Coarsegraining)
  * [settings](#Coarsegraining_settings)
  * [settings\_default](#Coarsegraining_settings_default)
  * [settings\_merged](#Coarsegraining_settings_merged)
  * [run](#Coarsegraining_run)
  * [output\_dataset](#Coarsegraining_output_dataset)
  * [output\_graphs](#Coarsegraining_output_graphs)
  * [output\_padem](#Coarsegraining_output_padem)
  * [export\_settings](#Coarsegraining_export_settings)

## [class CoarseGraining](#class_coarsegraining) <a href="#class_coarsegraining" id="class_coarsegraining"></a>

#### [iota.coarse\_graining.CoarseGraining(file, settings, dataset)](#Coarsegraining_ctor) <a href="#coarsegraining_ctor" id="coarsegraining_ctor"></a>

_CoarseGraining class object. This object contains the settings, the output and the run methods for a coarse-graining analysis._

**Parameters**

* `file`: (str) path and name to a coarse-graining settings file (Default: **None**)
* `settings`: (dict) coarse-graining settings given as a dictionary (Default: **None**)
* `dataset` : ([iota.dataset.Dataset](../dataset#class_dataset)) a dataset object to be used as input dataset for the coarse-graining analysis. If provided, it overwrites the input dataset of the coarse-graining settings (Default: **None**)

**Examples**

_Creating a CoarseGraining object with default settings_

```python
my_cg = iota.coarse_graining.CoarseGraining()
```

_Creating a CoarseGraining object based on the settings in an existing coarse-graining settings file_

```python
my_cg = iota.coarse_graining.CoarseGraining(file='C:/Users/Stephe/CGSettings/my_cg_settings.json')
```

_Creating a CoarseGraining object given on an existing settings dictionary_

```python
my_new_cg = iota.coarse_graining.CoarseGraining(settings=my_cg.settings)
```

_Creating a CoarseGraining object with default settings and an existing dataset object as the input dataset_

```python
my_cg = iota.coarse_graining.CoarseGraining(dataset=my_dataset)
```

_Creating a CoarseGraining object based on the settings in an existing coarse-graining settings file and using an existing dataset object as the input dataset_

```python
my_cg = iota.coarse_graining.CoarseGraining(file='C:/Users/Stephe/CGSettings/my_cg_settings.json', dataset=my_dataset)
```

_Creating a CoarseGraining object given on an existing settings dictionary and using an existing dataset object as the input dataset_

```python
my_new_cg = iota.coarse_graining.CoarseGraining(settings=my_cg.settings, dataset=my_dataset)
```

### Attributes

#### [CoarseGraining.settings](#Coarsegraining_settings) <a href="#coarsegraining_settings" id="coarsegraining_settings"></a>

_Get the coarse-graining settings that the user explicitly has set_

**Returns**

* A **dictionary** with the settings explicitly set by the user

**Example**

_Getting the settings of a coarse-graining object_

```python
my_cg_settings = my_cg.settings
print(my_cg_settings)
```

### Methods

#### [CoarseGraining.settings\_default()](#Coarsegraining_settings_default) <a href="#coarsegraining_settings_default" id="coarsegraining_settings_default"></a>

_Get the default coarse-graining settings_

**Returns**

* A **dictionary** with the default coarse-graining settings

**Example**

_Getting the default settings of a coarse-graining object_

```python
default_cg_settings = my_cg.settings_default()
print(default_cg_settings)
```

#### [CoarseGraining.settings\_merged()](#Coarsegraining_settings_merged) <a href="#coarsegraining_settings_merged" id="coarsegraining_settings_merged"></a>

_Get the complete coarse-graining settings that result from merging the settings explicitly set by the user and the default settings_

**Returns**

* A **dictionary** with the complete coarse-graining settings of the CoarseGraining object

**Example**

_Getting the complete settings of a CoarseGraining object_

```python
cg_settings = my_cg.settings_merged()
print(cg_settings)
```

#### [CoarseGraining.run()](#Coarsegraining_run) <a href="#coarsegraining_run" id="coarsegraining_run"></a>

_Run coarse-graining transformation based on the settings of the CoarseGraining object_

**Example**

_Running the coarse-graining transformation for the CoarseGraining object_

```python
cg_settings.run()
```

#### [CoarseGraining.output\_dataset()](#Coarsegraining_output_dataset) <a href="#coarsegraining_output_dataset" id="coarsegraining_output_dataset"></a>

_Get the dataset object that corresponds to the coarse-graining dataset generated after running the coarse-graining transformation_

**Return**

* A [**iota.dataset.Dataset**](../dataset#class_dataset) object that corresponds to the coarse-graining dataset

**Example**

_Getting the coarse-graining dataset generated after running coarse-graining transformation_

```python
my_cg.run()
my_cg_dataset = my_cg.output_dataset()
```

#### [CoarseGraining.output\_graphs()](#Coarsegraining_output_graphs) <a href="#coarsegraining_output_graphs" id="coarsegraining_output_graphs"></a>

_Get a list that contains the graphs object that may have been generated as result of the coarse-graining transformation_

**Return**

* A **list of** [**iota.graph.Graph** ](../graph#class_Graph)objects that correspond to the graphs generated by the coarse-graining transformation

**Example**

_Getting the list of graph objects generated after running coarse-graining transformation_

```python
my_cg.run()
my_cg_graphs = my_cg.output_graphs()
my_cg_graphs[0].display()
```

#### [CoarseGraining.output\_padem()](#Coarsegraining_output_padem) <a href="#coarsegraining_output_padem" id="coarsegraining_output_padem"></a>

_Get the dataset object that corresponds to the padem dataset that may have been generated after running the coarse-graining transformation. The padem dataset would contain the raw data of the particle based simulation in Particle Analytics format_

**Return**

* A [**iota.dataset.Dataset**](../dataset#class_dataset) object that corresponds to the padem dataset

**Example**

_Getting the padem dataset generated after running coarse-graining transformation_

```python
my_cg.run()
my_padem_dataset = my_cg.output_padem()
```

#### [CoarseGraining.export\_settings(file, merged)](#Coarsegraining_export_settings) <a href="#coarsegraining_export_settings" id="coarsegraining_export_settings"></a>

_Export the settings of a given CoarseGraining object to file in_ [_json_](https://www.json.org/) _format_

**Parameters**

* `file`: (str) path and name for the file where the settings will be exported to.
* `merged`: (bool) if True, the complete coarse-graining settings are exported, i.e., the settings resulting of merging the user settings and the default ones. If False, only the user settings are exported  (Default: **False**)

**Example**

_Exporting the coarse-graining settings set by the user to a file_

```python
my_cg.export(file='C:/Users/Stephen/CGsettings/my_cg_settings.json')
```

_Exporting the complete coarse-graining settings to a file_

```python
my_cg.export(file='C:/Users/Stephen/CGsettings/my_cg_settings.json', merged=True)
```
