Software decorator

The @software decorator is useful in order to move definitions of several PyCOMPSs decorators to a JSON file. It allows the users to ‘define’ their decorator definitions from an external file, which can be generated by another resource. Thus, the only supported argument is the ‘config_file’ that should contain the path to the JSON configuration file. Following example shows a basic usage of the @software decorator:

Code 89 Software decorator definition example.

from pycompss.api.task import task
from pycompss.api.software import software

@software(config_file="example.json")
@task(returns=1)
def example():
    return "hola"

Configuration files can contain different key-values depending on the user’s needs. Details of the configuration of the software execution can be defined in the value of the “execution” key. There the user can define the “type” of the execution and other necessary configuration parameters the software requires. Moreover, parameters of the PyCOMPSs @task can be added in the “parameters”.

For example, If we wanted to move the @task@ definition from the example above, inside the software the code and config file it would look like as follows:

Code 90 Example: task definition is inside the config file.

from pycompss.api.task import task
from pycompss.api.software import software

@software(config_file="example.json")
def example():
    return "hola"

Code 91 Task definition inside a software config file.

{
  "execution" : {
    "type":"task"
  },
  "parameters" : {
    "returns" : 1
  }
}

If the user wants to define an MPI task, then “mpi” value should be set for the “type” key. Moreover, arguments of PyCOMPSs’ @mpi decorator can be added. A basic configuration file for an MPI task would look like in the example below:

Code 92 JSON configuration file of an MPI definition.

{
  "execution" : {
    "type":"mpi",
    "runner": "mpirun",
    "binary":"date",
    "working_dir": "/tmp"
    },
  "parameters" : {
    "returns" : 1
  }
}

As we see “runner”, “processes”, and “binary” are the regular parameters of @mpi decorator, and are added as part of the execution configuration. However, parameters of the @task definition is are in the “parameters” key.

If we wanted to combine @constraint and @mpi decorators together, the JSON file would have been extended:

Code 93 JSON configuration file of an MPI definition.

{
    "execution": {
        "type":"mpi",
        "runner":"mpirun",
        "processes": 2,
        "binary":"~/app_mpi.bin",
            "args": "-d {{a}} {{b}}"
    },
    "parameters" : {
        "returns" : 1
    },
    "constraints":{
        "computing_units": 2
    }
}

It’s also possible to add @prolog and @epilog definitions in the configuration files:

Code 94 Prolog and Epilog definitions in configuration files.

{
    "execution": {
        "type":"mpi",
        "runner":"mpirun",
        "processes": 2,
        "binary":"app_mpi.bin",
            "args": "-d {{a}} {{b}}"
    },
    "parameters" : {
        "returns" : 1
    },
    "constraints":{
        "computing_units": 2
    },
    "prolog":{
        "binary":"echo",
        "args":"greetings from prolog."
    },
    "epilog":{
        "binary":"echo",
        "args":"execution finished."
    },
}

Next table provides more detailed information about JSON configuration files:

Key	Description
execution	(Mandatory) Contains all the software execution details such as “type” and arguments of the type’s decorator.
execution.type	(Mandatory) Type of the software invocation. Supported values are ‘task’, ‘workflow’, ‘mpi’, ‘binary’, ‘mpmd_mpi’, ‘multinode’, ‘http’, and ‘compss’.
parameters	A dictionary containing parameters regarding the “@task” definition.
prolog	Replaces the @prolog definition and expects @prolog parameters in a dictionary.
epilog	Replaces the @epilog definition and expects @epilog parameters in a dictionary.
constraints	Replaces the @constraint definition and expects @constraint parameters in a dictionary.
container	Replaces the @container definition and expects @container parameters in a dictionary.

Please check Other task types summary for the full list of the parameters for each decorator.