iTools run-script

The run-script command is used to run scripts based on PowSyBl.

Usage

$> itools run-script --help
usage: itools [OPTIONS] run-script --file <FILE> [--help]

Available options are:
    --config-name <CONFIG_NAME>   Override configuration file name

Available arguments are:
    --file <FILE>   the script file
    --help          display the help and quit

Required arguments

--file
This option defines the path of the script to execute. Current, only Groovy scripts are supported.

Groovy extensions

The run-script command relies on a plugin mechanism to load extensions. Those extensions provides utility functions to make the usage of PowSyBl easier through the scripts. It avoids the user to write boilerplate code hiding the technical complexity of framework into more user friendly functions. PowSyBl provides the following extensions to:

Load a network

The NetworkLoadSaveGroovyScriptExtension extension adds a loadNetwork function to load a network from a file. This function has two parameters:

  • the path of the file to load (mandatory)
  • a list of properties to configure the importer (optional). The list of supported properties depends on the grid format.

In order to benefit from this feature, add com.powsybl:powsybl-iidm-scripting to your classpath.

Example:

network = loadNetwork(filename, parameters)

Save a network

The NetworkLoadSave extension adds a saveNetwork function to load a network from a file. This function has four parameters:

  • the format of the output file (mandatory)
  • the network object to save (mandatory)
  • a list of properties to configure the exporter (optional). The list of supported properties depends on the output grid format.
  • the path of the output file (mandatory)

In order to benefit from this feature, add com.powsybl:powsybl-iidm-scripting to your classpath.

Example:

saveNetwork(format, network, parameters, file)

Run a power flow

The LoadFlow extension adds a loadflow function to run a power flow simulation to a network. This function has two parameters:

  • the network object (mandatory)
  • the load-flow parameters (optional). If this parameter is not set, the parameters are loaded from the the configuration.

In order to benefit from this feature, add com.powsybl:powsybl-loadflow-scripting to your classpath.

Example:

loadflow(network, parameters)

Access to AFS

The Afs extension adds a afs variable to the groovy binding that offers a facade to access data stored in AFS. This facade has two methods:

  • getFileSystemNames: this method returns the names of the file system declared in the configuration
  • getRootFolder: this method returns the root folder of the specified file system. From this root folder, it is possible to navigate in the different folders and open the different projects.

In order to benefit from this feature, add com.powsybl:powsybl-afs-scripting to your classpath.

Example

fileSystems = afs.getFileSystemNames()
for (String fs : fileSystems) {
    root = afs.getRootFolder(fs)
}

Examples

Example 1 - Hello World

The following example shows how to run a simple HelloWorld script. Note that the parameters pass to the command line can be accessed using the args array.

Content of the hello.groovy file:

print 'Hello ' + args[0]

To run this script, pass this file to the --file argument:

$> itools run-script hello.groovy John
Hello John

Example 2 - Run a power flow

The following example shows how to load a network from a file, run a power flow simulation and export the modified network to another file. This script is equivalent to the iTools loadflow command.

Content of the loadflow.groovy file:

import com.powsybl.loadflow.LoadFlowParameters.VoltageInitMode

input_file = argv[1]
output_file = argv[2]

// Load a network file
network = loadNetwork(input_file)

// Run a power flow, with custom parameters
parameters = new LoadFlowParameters()
parameters.voltageInitMode = VoltageInitMode.DC_VALUES
loadflow(network, parameters)

// Save the network to a file
saveNetwork("XIIDM", network, output_file)

To run the previous script, pass the input and output file names:

$> itools run-script loadflow.groovy XIIDM /tmp/case.xiidm /tmp/case-lf.xiidm

Going further