(beta) .torchxconfig file

You can store the scheduler run cfg (run configs) for your project by storing them in the .torchxconfig file. Currently this file is only read and honored when running the component from the CLI.

CLI Usage

1. cd into the directory where you want the .torchxconfig file to be dropped. The CLI only picks up .torchxconfig files from the current-working-directory (CWD) so chose a directory where you typically run torchx from. Typically this is the root of your project directory.

2. Generate the config file by running

   $ torchx configure -s <comma,delimited,scheduler,names>
   
   # -- or for all registered schedulers --
   $ torchx configure
   

3. If you specified -s local_cwd,kubernetes, you should see a .torchxconfig file as shown below:

   $ cat .torchxconfig
   [local_cwd]
   
   [kubernetes]
   queue = #FIXME:(str) Volcano queue to schedule job in
   

4. .torchxconfig in in INI format and the section names map to the scheduler names. Each section contains the run configs for the scheduler as $key = $value pairs. You may find that certain schedulers have empty sections, this means that the scheduler defines sensible defaults for all its run configs hence no run configs are required at runtime. If you’d like to override the default you can add them. TIP: To see all the run options for a scheduler use torchx runopts <scheduler_name>.

5. The sections with FIXME placeholders are run configs that are required by the scheduler. Replace these with the values that apply to you.

6. IMPORTANT: If you are happy with the scheduler provided defaults for a particular run config, you should not redundantly specity them in .torchxconfig with the same default value. This is because the scheduler may decide to change the default value at a later date which would leave you with a stale default.

7. Now you can run your component without having to specify the scheduler run configs each time. Just make sure the directory you are running torchx cli from actually has .torchxconfig!

   $ ls .torchxconfig
   .torchxconfig
   
   $ torchx run -s local_cwd ./my_component.py:train
   

Programmatic Usage

Unlike the cli, .torchxconfig file is not picked up automatically from CWD if you are programmatically running your component with torchx.runner.Runner. You’ll have to manually specify the directory containing .torchxconfig.

Below is an example

from torchx.runner import get_runner
from torchx.runner.config import apply
import torchx.specs as specs

def my_component(a: int) -> specs.AppDef:
   # <... component body omitted for brevity ...>
   pass

scheduler = "local_cwd"
cfg = {"log_dir": "/these/take/outmost/precedence"}

apply(scheduler, cfg, dirs=["/home/bob"])  # looks for /home/bob/.torchxconfig
get_runner().run(my_component(1), scheduler, cfg)

You may also specify multiple directories (in preceding order) which is useful when you want to keep personal config overrides on top of a project defined default.

Config API Functions

torchx.runner.config.apply(scheduler: str, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str]]]], dirs: Optional[List[str]] = None) → None

Loads a .torchxconfig INI file from the specified directories in preceding order and applies the run configs for the scheduler onto the given cfg.

If no dirs is specified, then it looks for .torchxconfig in the current working directory. If a specified directory does not have .torchxconfig then it is ignored.

Note that the configs already present in the given cfg take precedence over the ones in the config file and only new configs are added. The same holds true for the configs loaded in list order.

For instance if cfg={"foo":"bar"} and the config file is:

# dir_1/.torchxconfig
[local_cwd]
foo = baz
hello = world

# dir_2/.torchxconfig
[local_cwd]
hello = bob

Then after the method call, cfg={"foo":"bar","hello":"world"}.

torchx.runner.config.load(scheduler: str, f: TextIO, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str]]]]) → None

loads the section [{scheduler}] from the given configfile f (in .INI format) into the provided runcfg, only adding configs that are NOT currently in the given runcfg (e.g. does not override existing values in runcfg). If no section is found, does nothing.

torchx.runner.config.dump(f: TextIO, schedulers: Optional[List[str]] = None, required_only: bool = False) → None

Dumps a default INI-style config template containing the :py:class:torchx.specs.runopts for the given scheduler names into the file-like object specified by f. If no schedulers are specified dumps all known registered schedulers.

Optional runopts are pre-filled with their default values. Required runopts are set with a FIXME: ... placeholder. To only dump required runopts pass required_only=True.

Each scheduler’s runopts are written in the section called [{scheduler_name}].

For example:

[kubernetes]
namespace = default
queue = #FIXME (str)Volcano queue to schedule job in

Raises

ValueError – if given a scheduler name that is not known