Dear all,

TLDR; We recently migrated yt's configuration system from the yt-3 format to a new and more flexible format in yt-4 (the toml format, see https://github.com/yt-project/yt/pull/2981). This requires a manual intervention to perform the migration (see details below).

What does it change for users?

The new configuration system is documented online here: https://yt-project.org/docs/dev/reference/configuration.html.

Performing the migration

The change requires a one-time manual intervention on your side to perform the migration automatically. To perform the migration, simply type in your console

    yt config migrate

This should migrate your old configuration to the new format (stored in ~/.config/yt/yt.toml) and store a backup of your old configuration file in ~/.config/yt/ytrc.bak should any error happen. Please report any issue you may encounter in the migration procedure so that we can fix them before releasing officially yt-4.

If you get an error about a missing toml package, you may also have to install the toml package manually


    conda install -c conda-forge toml    # if you are using conda
    pip install toml                     # otherwise


Per-folder configuration

The new configuration system allows you to configure yt per-folder. In particular, if a file named yt.toml is present in your current working folder, this file will override the global configuration. You can easily configure yt from the command line using

    yt config set yt log_level 40 --global  # this will write in ~/.config/yt/yt.toml
    # or
    yt config set yt log_level 40 --local   # this will write in ./yt.toml

Naming convention

We have also rationalized the naming convention of configurable keys in the configuration file: all keys now use snake case (i.e. words separated by an underscore). For example loglevel has become log_level. This is handled automatically by the configuration script, but bear that in mind if you modify the configuration file. For reference, all configurable keys can currently be found online https://github.com/yt-project/yt/blob/main/yt/config.py#L12 and the most important ones are documented online (https://yt-project.org/docs/dev/reference/configuration.html).

What does it change for developers?

The new format should allow more flexible configuration options. In particular, it supports nested configuration blocks and allows to find the most specific key in the configuration file

# yt.toml
[fields]
cmap = "arbre"

[fields.gas]
cmap = "viridis"

[fields.gas.temperature]
cmap = "plasma"

In Python, you can then query the "most specific" key matching a given path:

from yt.config import ytcfg
ytcfg.get_most_specific("fields", "gas", "temperature", "cmap") == "plasma"
ytcfg.get_most_specific("fields", "gas", "density", "cmap") == "viridis"
ytcfg.get_most_specific("fields", "io", "velocity_x", "cmap") == "arbre"

This isn't used anywhere yet. The other breaking change compared to the old configuration system is that ytcfg.get returns typed quantities (as read by the toml parser) instead of strings.

Best,
Corentin

-- 
Dr. Corentin Cadiou
Post Doctoral Research Assistant
Cosmoparticle Initiative Hub, desk 27
University College London (UCL)
Gower St, Bloomsbury, London WC1E 6BT

mobile: +33.6.43.18.66.83