FLARE Commandline Interface#

The FLARE Commandline Interface (CLI) is the entry point for all things FLARE. Here we will discuss the various tools within that a user can utilize for their workflow requirements.

FLARE Run#

$ flare run -- help
< INSERT THE OUTPUT>
mcproduction, analysis

The run method is the entry point in which a user can run their workflow. Currently, there are 2 workflows implemented into FLARE, the mcproduction and analysis. Irrespective of which one you choose, they have a set of common arguments.

options:
  -h, --help            show this help message and exit
  --name NAME           Name of the study
  --version VERSION     Version of the study
  --description DESCRIPTION
                        Description of the study
  --study-dir STUDY_DIR
                        Study directory path where the files for production are located
  --output-dir OUTPUT_DIR
                        The location where the output file will be produced, by default will be the current working directory
  --config-yaml CONFIG_YAML
                        Path to a YAML config file

--name and --version#

Important to note is that the --name and --version options will affect the output directory structure. For example if the following command is ran:

flare run analysis --name docs --version 1.0

The output data directory that FLARE creates will have the following structure:

data/docs/1.0/...

This design means if a workflow needs to be rerun with slight changes one can just change the name OR version number depending on what suits the user’s needs.

--description#

The --description option allows the user to provide a description of their workflow, what it is achieving or what assumptions one should know if they are to revisit this workflow in the future. The text provided is bundled into a README.md file located inside the output directory structure, e.g.:

ls data/docs/1.0/README.md

--study-dir#

It is common practice to store your workflow input files in your current working directory. However, this option allows a user to tell FLARE if a different directory contains the input files for the workflow.

flare run mcproduction --study-dir ../different_input_files

--output-dir#

By default all the output directory structure of FLARE is created in the current working directory. If a user wishes to have the output directory structure located elsewhere, they can provide a path via the --output-dir option.

flare run analysis --output-dir ../../central_FLARE_outputs

FLARE run analysis: --mcprod#

The flare run analysis command has one additional argument, namely --mcprod.

Workflow Settings with `flare.yaml`#

The flare.yaml is the configuration file located in your current working directory. This is where FLARE will look for additional configuration settings required for the workflow.

It is also the location in which a user can interact with the b2luigi backend settings manager.

Customizable FLARE Settings#

This yaml file allows a user to set the --name, --version and --description from the CLI tool. This can simplify the running of a workflow by having these settings defined in this central yaml file rather than adding it to the CLI command each time a workflow is ran.

# flare.yaml
name: docs
version: 1.0
description: This workflow is defined in the documentation

As mentioned, a user can set any b2luigi settings here in the flare.yaml. Importantly, this is where a user can set the batch_system setting, informing FLARE which batch system to submit to. FLARE can submit to the following batch systems:

Slurm
LSF
HTCondor

If your batch system is not available, new ones can easily be added — checkout the b2luigi docs for more information.

# flare.yaml
name: docs
version: 1.0
description: This workflow is defined in the documentation

# b2luigi settings
batch_system: lsf

FLARE Settings Hierarchy#

1. CLI Interface
      |
      v
2. FLARE yaml settings
      |
      v
3. Default Settings

The FLARE settings manager works on a hierarchy. FLARE prioritizes the settings passed to the CLI. If a setting was not passed there, FLARE will next refer to the flare.yaml. Lastly, if a setting value is not provided, a default is used.

FLARE uses Pydantic to validate user input data. The exact Pydantic model along with the defaults are shown below.

from pathlib import Path

class UserConfigModel(BaseModel):
    name: str = Field(default="default_name")
    version: str = Field(default="1.0")
    description: str = Field(default="No Description")
    studydir: Path | str = Field(default_factory=Path.cwd)
    outputdir: Path | str = Field(default_factory=Path.cwd)

FLARE lint#

flare lint fccanalysis

The FLARE linting tool is an addition to version 0.3.0 which will crawl through workflow input files and ensure they are formatted correctly. To use the tool, a user must be in the working directory in which their input workflow files are located.

The FLARE linter is designed to enforce the following FLARE Principles:

FLARE has full control of the input and output directories of workflow data.
For each Task required by a user, there must exist a unique script for that step.
Every Task in FLARE can have at most one required Task. I.e. each Task can have a single input data directory to draw from.

These principles are especially important when utilizing the Add Custom Tasks feature of FLARE.

FLARE Commandline Interface

Contents