Bifrost executor payload
Using the Bifrost executor, this payload needs to be provided when submitting a job using the Create job endpoint. Currently Bifrost 2.9.0.0 will be used when submitting job using the Bifrost executor if no version is provided in the payload options.
Working with Bifrost graphs
Use Maya to create and edit a Bifrost graph. See the documentation on how to build and modify graphs. Once a graph is created, it can be published as a JSON file. This graph file can be used with the Bifrost executor inside the Flow Graph Engine API. See the Maya documentation on publishing effects as graphs. Typically, to find value in running a graph on the Flow Graph Engine, the graph will be built and configured to produce some output file(s) on disk that can be retrieved as output in the API.
Available Bifrost versions
When using the Bifrost executor, different versions of Bifrost are available to execute a graph. It is strongly recommended to select the exact version of Bifrost for which the graph was created using the bifrostVersion attribute in the options. The currently available versions are 2.9.0.0, 2.10.0.0, and 2.11.0.0. It is recommended to always provide the bifrostVersion option as the default bifrost version being used when it is not provided is subject to change in the future.
Payload Structure
payload* object | Specifies the Bifrost-specific information indicating what Bifrost should do. |
action* enum:string | Specifies the overall action that Bifrost should perform for this job.
Possible values: Evaluate , ListPorts |
options* object | Additional options for this job. |
compound* string | Specifies the fully qualified name for the Bifrost compound to evaluate. |
frames object | Specifies which frames the job should iterate over. Using this option implies that this is a multi-frame sequential evaluation. |
start int | The number of the first frame in the sequence. |
end int | The number of the last frame in the sequence. |
fps number | The frames per second value to use together with the frames to deduce time. |
terminalStates array: object | The state of the terminals for the executions |
name* string | The fully qualified name of the port description of the terminal. |
enabled* boolean | Whether the given terminal is enabled when the graph is executed. |
* | |
maxPerExecutionTimeInSeconds int | Max execution time for each execution, specified in seconds. The API will attempt to limit the execution to run for no longer than this. Can be set to up to 86400 seconds (24 hours).
Note: Additional limitations may apply, meaning that a execution may be canceled prior to reaching this limit. |
bifrostVersion string | The version of Bifrost to be used to execute the graph. The default is 2.9.0.0 |
definitionFiles array: object | The list of Bifrost definition files to load |
details object | Provides task executor-specific additional details for the input resource |
source* one of | Represents an external storage location, either a URI or a reference info a storage space. |
URI storage location* object | A URI where a particular resource is located. |
uri* string | The resource URI |
** | |
Space storage location* object | Represents a storage location within a specific storage space |
key* string | The unique key within the storage space that refers to the particular object within the space. |
spaceId* string | An ID for a specific storage space, unique within the job |
** | |
target object | Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found. |
path string | A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.
Max length: 4000 |
ports object | The list of ports to set |
inputPorts array: object | List of input ports to set |
name* string | The name of the port to be set. |
value* string | The value to set, as a JSON value serialized to string |
type* string | The port type. |
* | |
jobPorts array: object | List of job ports to set |
name* string | The name of the port to be set. |
value* string | The value to set, as a JSON value serialized to string |
type* string | The port type. |
* | |
executions array: object | List of executions of the Bifrost graph to perform. Each execution specifies a set of configurations to be applied to the graph. |
inputs array: object | List of inputs that are required for this execution. |
details object | Provides task executor-specific additional details for the input resource |
source* one of | Represents an external storage location, either a URI or a reference info a storage space. |
URI storage location* object | A URI where a particular resource is located. |
uri* string | The resource URI |
** | |
Space storage location* object | Represents a storage location within a specific storage space |
key* string | The unique key within the storage space that refers to the particular object within the space. |
spaceId* string | An ID for a specific storage space, unique within the job |
** | |
target object | Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found. |
path string | A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.
Max length: 4000 |
outputs array: object | List of expected outputs for this execution. |
details object | Additional executor-specific details for the expected output from a task. |
source object | Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found. |
path string | A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.
Max length: 4000 |
target* object | Information about an expected output from a task. The output can be retrieved by clients using the resulting output path, which has the general format ‘[/{taskName}][/{taskIndex}]/{outputName}’, where the output name corresponds to the name property of the output. |
name* string | A ‘path’ identifier to uniquely access an output or log produced by a task. The general format is ‘[/{taskName}][/{executionIndex}]/{outputName}’. |
jobPorts array: object | List of job ports to set for this execution. |
name* string | The name of the port to be set. |
value* string | The value to set, as a JSON value serialized to string |
type* string | The port type. |
* | |
inputPorts array: object | List of input ports to set for this execution. |
name* string | The name of the port to be set. |
value* string | The value to set, as a JSON value serialized to string |
type* string | The port type. |
* | |
templateRange one of | The range of values that the template should be instantiated over. |
Range sequence object | A range of integers from start to end (inclusive). |
start* int | The first value in the range |
end* int | The last value in the range |
* | |
Range array array: integer | A sequence of integers to be used as a range in a template. |
frameId one of | Sets the frame number for the execution.
Note: Frame Ids must be set for all or none of the executions. |
Frame Id int | Frame Id to use to set time for this execution. |
Frame Id Template string | Template that is instanced to generate the Frame Ids for templated executions. |
* |
Templated Executions
Templating facilitates the definition of multiple executions by specifying patterns and mappings.
The templateRange
attribute specifies a range or list of numbers that can be used to replace patterns in file paths, and in the frameId
attribute.
The typical use case is to create a series of executions mapping to specific frames with different inputs.
Note that job ports and input ports cannot have patterns as part of the template.
Here is an example of how to use the templateRange
attribute in the payload along with the frameId
attribute:
{
"executions": [
{
"templateRange": {
"start": 5,
"end": 10
},
"frameId": "{executionId:01d}",
"inputPorts": [],
"jobPorts": [],
"inputs": [
{
"source": {
"key": "graph_inputs.{executionId:04d}.bob",
"spaceId": "scratch:@default"
},
"target": {
"path": "graph_inputs/graph_inputs.{executionId:04d}.bob"
}
}
],
"outputs": [
{
"source": {
"path": "output{executionId:03d}.bob"
},
"target": {
"name": "output{executionId:03d}.bob"
}
}
]
}
]
}
In this example, the templateRange
attribute specifies a range from 5 to 10. One execution is created for each number in the range by replacing executionId
in patterns in the inputs and outputs as well as in the optional frameId
attribute.
The frameId
attribute maps each execution to a frame, so the associated Bifrost graph will be executed for frames 5 through 10.
Format String in Patterns
The format strings follow the Python format syntax. Formatted string literals (also called f-strings) let you include the value of Python expressions inside a string by writing expressions as {expression}.
An optional format specifier can follow the expression to control how the value is formatted.
Currently, the only expression allowed is executionId
, which will be replaced by a number from the template range when an execution is created from a templated execution.
For example, if you have an input file named graph_inputs.###.bob for a file cache writing node in Bifrost, the corresponding format string should be graph_inputs.{executionId:03d}.bob for the input field in the payload. The expression {executionId:03d} is substituted for the current number from the template range, zero-padded to three digits.
Executions Ordering and Merging
All executions that specify the same frame ID are merged into a single execution, and executions are performed ordered by frame ID, smallest first. If frame IDs are not specified in the executions, they are performed in the order they appear in the task definition. Note that either all or none of the executions should specify a frame ID.
In this example, the definitions for frame 5 within the templated execution and for the specific execution for frameId
5 will be combined into one:
{
"executions": [
{
"templateRange": {
"start": 1,
"end": 10
},
"frameId": "{executionId:01d}",
"outputs": [
{
"source": {
"key": "graph_outputs.{executionId:04d}.bob",
"spaceId": "scratch:@default"
},
"target": {
"path": "graph_outputs/graph_outputs.{executionId:04d}.bob"
}
}
]
},
{
"frameId": 5,
"inputs": [
{
"source": {
"key": "graph_inputs.0005.bob",
"spaceId": "scratch:@default"
},
"target": {
"path": "graph_inputs/graph_inputs.0005.bob"
}
}
]
}
]
}
Optional frames Attribute
The optional frames
attribute can be used to specify the start and end frames for sequential multi-frame executions.
When a frame range is specified, the set of executions is validated to ensure there is one execution per frame.
When frame IDs are not explicitly specified on the executions, the executions will be mapped to frames using the frames
range, and the number of executions must match the number of frames in the range.
Here is an example of how to use the frames
attribute in the payload:
{
"options": {
"frames": {
"start": 11,
"end": 20
}
},
"executions": [
{
"templateRange": {
"start": 1,
"end": 10
},
"inputs": [
{
"source": {
"key": "graph_inputs.{executionId:04d}.bob",
"spaceId": "scratch:@default"
},
"target": {
"path": "graph_inputs/graph_inputs.{executionId:04d}.bob"
}
}
]
}
]
}
The templateRange
attribute generates input files using the numbers 1 to 10, and the frames
attribute sets the frame IDs to 11 through 20 for the executions.
Please be aware that a mismatch between the template range and frame IDs may lead to mismatched file paths during the execution of the graph. This can happen for instance if the Bifrost graph contains file patterns that need to be replaced by frame IDs, but the file paths where instantiated using a mismatched template range. This can lead to failure to perform the execution, or to unexpected results.