# 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)
```


---

# 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-user-manual/iota-python-reference-library/coarsegraining.md?ask=<question>
```

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.