Using the ScriptTask to execute commands¶
The ScriptTask is a Firetask built-in to FireWorks to help run non-Python programs through the command line. For example, you could use the ScriptTask to execute a Java “JAR” file or a C++ code. Internally,ScriptTask runs your script through a thin Python wrapper (the ScriptTask is really just another Firetask and doesn’t have any special privileges).
The advantage of the built-in ScriptTask is that a lot of features and options have already been implemented. Let’s examine these now.
The ScriptTask parameter requires setting the script parameter:
script- (str) or [(str)] - a String script to run, or an array of scripts to run in sequence
The ScriptTask can take in many parameters. We already examined the
script parameter of ScriptTask in the Introductory tutorial; this parameter sets the script to run. It is the only required parameter. Other optional parameters are:
defuse_bad_rc- (default:False) - if set True, a non-zero returncode from the Script (indicating error) will cause FireWorks to defuse the child FireWorks rather than continuing.
fizzle_bad_rc- (default:False) - if set True, a non-zero returncode from the Script (indicating error) will cause the Firework to raise an error and FIZZLE.
use_shell- (default:True) - whether to execute the command through the current shell (e.g., BASH or CSH). If true, you will be able to use environment variables and shell operators; but, this method can be less secure.
shell_exe- (default:None) - path to shell executable, e.g. /bin/bash. Generally you do not need to set this unless you want to run through a non-default shell.
stdin_file- (default:None) - feed this filepath as standard input to the script
stdin_key- (default:None) - feed this String as standard input to the script
store_stdout(default:False) - store the entire standard output in the Firework Launch object’s stored_data
stdout_file- (default:None) - store the entire standard output in this filepath. If None, the standard out will be streamed to sys.stdout
store_stderr- (default:False) - store the entire standard error in the Firework Launch object’s stored_data
stderr_file- (default:None) - store the entire standard error in this filepath. If None, the standard error will be streamed to sys.stderr
These parameters do not go in the root of the FW spec. Rather, they go as parameters to the
ScriptTask in the
_tasks section of the spec (in the same section as the
script parameter in the Introductory tutorial).
Manually setting the ScriptTask FWAction¶
The built-in ScriptTask options might not be flexible enough to handle all your needs. For example, you might want to return a complex FWAction that stores custom data from your job and modifies the Workflow in a complex way (within, for example your Java or C++ code).
To accomplish this, your script can write a file called
FWAction.yaml in the launch directory, and that contains a serialization of the FWAction object. FireWorks will read this file and replace the simple FWAction returned by ScriptTask with the one you specify in this file.
The _use_global_spec option¶
By default, the parameters for the ScriptTask should be defined within the
_task section of the spec corresponding to the ScriptTask, not as a root key of the spec. If you’d like to instead specify the parameters in the root of the spec, you can set
_use_global_spec to True within the
_task section. Note that
_use_global_spec can simplify querying and communication of parameters between FireWorks but can cause problems if you have multiple ScriptTasks within the same Firework.