> For the complete documentation index, see [llms.txt](https://particle-analytics-1.gitbook.io/iota-user-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://particle-analytics-1.gitbook.io/iota-user-manual/iota-python-reference-library/coarsegraining.md).

# iota.coarsegraining

**Description**

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

* [CoarseGraining](/iota-user-manual/iota-python-reference-library/coarsegraining.md#class_Coarsegraining)
  * [settings](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_settings)
  * [settings\_default](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_settings_default)
  * [settings\_merged](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_settings_merged)
  * [run](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_run)
  * [output\_dataset](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_output_dataset)
  * [output\_graphs](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_output_graphs)
  * [output\_padem](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_output_padem)
  * [export\_settings](/iota-user-manual/iota-python-reference-library/coarsegraining.md#Coarsegraining_export_settings)

## [class CoarseGraining](/iota-user-manual/iota-python-reference-library/coarsegraining.md#class_coarsegraining) <a href="#class_coarsegraining" id="class_coarsegraining"></a>

#### [iota.coarse\_graining.CoarseGraining(file, settings, dataset)](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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](/iota-user-manual/iota-python-reference-library/dataset.md#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](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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**](/iota-user-manual/iota-python-reference-library/dataset.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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** ](/iota-user-manual/iota-python-reference-library/graph.md#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()](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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**](/iota-user-manual/iota-python-reference-library/dataset.md#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)](/iota-user-manual/iota-python-reference-library/coarsegraining.md#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)
```