Getting started with Iota Python Library and Iota IPython Terminal

This section provides an introduction on how to start using the Iota Python Library from the Iota IPython Terminal. The Iota iPython Terminal is installed during the installation process of Iota and is available at the Start menu of your OS inside the "Iota Suite" folder (see Figure 1).

Figure 1 - Start menu entry on Windows where Iota IPython Terminal is highlighted

The Iota iPython Termnial is a iPython command shell that allows the users to perform computational operations in an interactive way and provides some useful features including:

• Comprehensive object introspection

• Shell syntax

• Tab completion

• Commands history

For More detailed information about iPython command shell, users can visit the official IPython documenation .

Executing the Iota IPython Terminal open an IPython terminal like the one shown in Figure 2. The IPython terminal is automatically started on the Iota Suite installation directory (e.g. "C:\Program Files\iota_suite").

Figure 2 - Iota IPython terminal

Once the Iota IPython terminal is open, users need to import the Iota Python Library. To do so, users need to execute the following command on the terminal:

 import iota

This will load the Iota Python Library so that the users can have to the whole content on the library via the object iota (see the Iota Python Reference Library for more detailed information about the content of the library).

Starting a Session

Users can start a session using the iota.session function that give access to the database and allows you load existing projects, create new ones and other actions as explained in iota.session documentation:

my_session = iota.session('my_Iota_username','my_home_folder/ParicleAnalytics/config.ini')

where my_Iota_username needs to be replaced by to your registered username in Iota and my_home_folder by your home directory on your operative sysem (e.g. C:/Users/Stephen).

Once the session has been started, you can ask for the list of projects in your database:

my_session.projects

that will return a list containing the project including their manes and a brief summary of the scenario and assets contain in the project:

[<Project: Backhoe optimization (2 scenarios, 2 files, 8, graphs, 3 meshes, 4 datasets),
 <Project: Rotary Drum mixer (2 scenarios, 0 files, 20, graphs, 3 meshes, 4 datasets),
 <Project: Soil tillage (1 scenarios, 0 files, 4, graphs, 0 meshes, 2 datasets),

Creating a New Project

Once an iota.session can has been started, users can create new projects in their database using the method create_project:

my_project = my_session.create_project(name='My New Project', description='This is my new project')

Loading a Project

Users can load existing projects by their names using the method get_project of the iota.session object:

my_project = my_session.get_project('Backhoe optimization')

In this example, the iota.session.project object is stored in the variable my_project.

Creating-a-scenario

Users can create new scenario using the method add_scenario of the iota.session object:

my_scenario = my_project.add_scenario(name='Initial design', description='This is my new scenario')

Loading a Scenario

Users can load a scenario using the method get_scenario of the iota.session object:

my_scenario = my_project.get_scenario('Initial design')

Importing a Dataset

Users can import a dataset into the scenario using the method add_dataset for datasets in PADEM and PACG format.

my_scenario.add_dataset(name = 'backhoe_coarse-graining', data_format = 'PACG',file = '/path/to/my/pacg/dataset/backhoe_cg.meta')

In case of EDEM 2017+ format, users can import the EDEM simulation by using the method import_dataset:

my_scenario.import_dataset(file = '/path/to/my/edem/dataset/simulation.dem', name = 'Backhoe Initial desing', data_format = 'EDEM 2017',include_graphs = True)

Note that include_grahs=True sets the generation and importing into the scenario of the reaction force and torque graphs of each geometry contained in the EDEM simulation to be imported.

Running Coarse-graining

Users can run the coarse-graining analysis of a scenario using the method run_coarse_graining of the scenario object:

my_scenario.run_coarse_grainig()

In this example, coarse-graining would be run using the existing coarse-graining settings of scenario that the user may have set via the Graphical User Interface. For more information on how to run coarse-graining with custom settings using the Iota Python Library, please see get_coarse_graining_settings and run_coarse_graining_settings in the section Scenario of the Iota Python Reference Library.