Writing Scripts

Users can write their own Python scripts (.py) using the methods provided with the Iota Python Library. This allows users to customize and create more sophisticated analysis workflows that then can be reproduced by running the scripts instead of executing manually one by one the commands on the Iota IPython Terminal. The scripts can be written using text editor or Python Editor that use the Iota Python Library.

Generic Scripts

This is an example of generic Python script using Iota Python Library:

''' This scripts loads an existing project and for each scenario of the project, it runs 
coarse-graining using the coarse-graining settings that were previously set via the GUI'''

### Import Python modules and add IOTA installation path to Python paths
import sys                              
import os
import iota
sys.path.append(os.getenv('IOTA_PATH'))

### Set your Iota username and home directory

username = 'stephen'
home_path = 'C:/Users/stephen/'


### Star a new iota session
my_session = iota.session(username,home_path + 'ParticleAnalytics/config.ini')


### Main actions 
project = my_session.get_project('Backhoe optimization')                      

ListOfScenarios = project.get_scenarios()                                     

for sc in ListOfScenarios:                                                     
    print('Starting coarse-graining of {}'.format(sc.name))
    sc.run_coarse_graining()                                         
    print('Finished coarse-graining of {}'.format(sc.name))

The script can be split in different sections:

1. Script description (optional): summary of that describes what the script intends to do.

   ''' This scripts loads an existing project and for each scenario of the project, it runs 
   coarse-graining using the coarse-graining settings that were previously set via the GUI'''

2. Importing modules & adding IOTA installation path: this section imports the Iota Python Library (iota) and the Python modules sys and os that are used to add the installation path of Iota to the Python paths:

   import sys                              
   import os
   import iota
   sys.path.append(os.getenv('IOTA_PATH'))

3. Setting your Iota username and home directory: this section assign your Iota username and home directory path to the variables username and home_path. This variable are used in the next section of the script to start your Iota session.

   username = 'stephen'
   home_path = 'C:/Users/stephen/'

4. Starting a new Iota session: this section starts a new Iota session using the username and home directory set in the previous section:

   username = 'stephen'
   home_path = 'C:/Users/stephen/'

5. Main actions: this section includes the main actions that you want to conduct and automate with the script. In this particular example:

Load the project called "Backhoe optimization"

Get the list of scenarios in the project

For each scenario in the list of scenarios
    Show on the terminal that the coarse-graining for the scenario X is starting
    run coarse-graining using the settings of the scenario
    Shown on the terminal that the coarse-graining for the scenario X has finished

project = my_session.get_project('Backhoe optimization')                       

ListOfScenarios = project.get_scenarios()                                      

for sc in ListOfScenarios:                                                    
    print('Starting coarse-graining of {}'.format(sc.name))
    sc.run_coarse_graining()                                                   
    print('Finished coarse-graining of {}'.format(sc.name))

Note that the sections 2 - 5 of the scripts can be re-used for any other generic script so that users just need to modify sections 1 and 5 depending on the description and actions that they want to perform with the script.

Run(scenario) Scripts

An example of run Script can be found below. The difference with the generic scripts is that this scripts need to include the definition of the function def run(scenario) and the actions to be performed by the script are included inside that function. This kind of scripts can be imported into a project/scenario and then also attached as Post-Analysis when setting the coarse-graining analysis (for more details see the "Scritps" and "Post-Analysis" sections of the Iota User Mananul.

''' This scripts load the coarse-graining dataset of the scenario and create a cut-plane of the mesh called "Simulation_domain" with results for each timestep of the dataset. The cut-planes are automatically saved into the coarse-graining dataset'''

import iota

def run(scenario):

    mesh_name = 'Simulation_Domain'                  #Name of the mesh to be cut
    origin = [0,0,0.3]                               #Positon of origin of the cut plane
    normal_direction = [0,0,1]                       # Normal direction of the cut plane

    cg_dataset = scenario.get_cg_dataset()           # Load the coarse-graining dataset of the scenario
    cg_data = cg_dataset.data()                      # Load the data of the coarse-graining dataset
    NumberOfTimeSteps = len(cg_data.timesteps())     # Get the number of timesteps

    for cont in range(0,NumberOfTimeSteps):                                                  #For each timestep
        cg_data.add_slice(step=cont, cg_data.add_slice(mesh='Simulation_Domain',
            normal=iota.Vector3d(normal_direction), origin=iota.Vector3d(origin))    #Create and save the cut-plane

The script can be split in different sections:

1. Script description: summary of that describes what the script intends to do.

   ```python

   ''' This scripts load the coarse-graining dataset of the scenario and create a cut-plane of the mesh called "Simulation_domain" with results for each timestep of the dataset. The cut-planes are automatically saved into the coarse-graining dataset'''

2. Importing modules: in this example, only the Iota Python Library (iota) is imported but user can import any other available python modules.

   import iota

3. definition of the "run" method: the method run is defined as takes as argument a variable called scenario (i.e, a scenario object of the Iota Python Library)

   def run (scenario):

4. Main actions: this section includes the main actions that to be conducted with the script. In this particular example:

Set "Simulation_Domain" as the mesh to be cut
Set [0,0,0.3] as the position [X,Y,Z] for the origin point of the cut-plane
Set [0,0,1] as the normal direction [X,Y,Z] of the cut-plane
Load the coarse-graining dataset of the scenario
Load the data of the coarse-graining dataset
Get the number of timesteps of the dataset
For counter values in the range 0 to the number of timesteps
    At the step of the counter, create and add to the coarse-graining dataset a cut plane of the mesh name
     based on the given origin and normal direction

mesh_name = 'Simulation_Domain' #Name of the mesh to be cut
origin = [0,0,0.3] #Positon of origin of the cut plane
normal_direction = [0,0,1] # Normal direction of the cut plane

cg_dataset = scenario.get_cg_dataset() # Load the coarse-graining dataset of the scenario
cg_data = cg_dataset.data() # Load the data of the coarse-graining dataset
NumberOfTimeSteps = len(cg_data.timesteps()) # Get the number of timesteps
for cont in range(0,NumberOfTimeSteps): #For each timestep
cg_data.add_slice(cg_data.add_slice(mesh='Simulation_Domain',
normal=iota.Vector3d(normal_direction), origin=iota.Vector3d(origin)) #Create and save the cut-plane