Customizing yt: The Configuration and Plugin Files¶
yt features ways to customize it to your personal preferences in terms of
how much output it displays, loading custom fields, loading custom colormaps,
accessing test datasets regardless of where you are in the file system, etc.
This customization is done through The Configuration and
Plugin Files both of which exist in your
The configuration is stored in simple text files (in the toml format). The files allow to set internal yt variables to custom default values to be used in future sessions. The configuration can either be stored globally or locally.
If no local configuration file exists, yt will look for and recognize the file
$HOME/.config/yt/yt.toml as a configuration file, containing several options
that can be modified and adjusted to control runtime behavior. For example, a sample
$HOME/.config/yt/yt.toml file could look
[yt] log_level = 1 maximum_stored_datasets = 10000
This configuration file would set the logging threshold much lower, enabling
much more voluminous output from yt. Additionally, it increases the number of
datasets tracked between instantiations of yt. The configuration file can be
managed using the
yt config --global helper. It can list, add, modify and remove
options from the configuration file, e.g.:
$ yt config -h $ yt config list $ yt config set yt log_level 1 $ yt config rm yt maximum_stored_datasets
yt will look for a file named
yt.toml in the current directory, and upwards
in the file tree until a match is found. If so, its options are loaded and any
global configuration is ignored. Local configuration files can contain the same
options as the global one.
Local configuration files can either be edited manually, or alternatively they
can be managed using
yt config --local. It can list, add, modify and remove
options, and display the path to the local configuration file, e.g.:
$ yt config -h $ yt config list --local $ yt config set --local yt log_level 1 $ yt config rm --local yt maximum_stored_datasets $ yt config print-path --local
If no local configuration file is present, these commands will create an (empty) one in the current working directory.
Configuration Options At Runtime¶
In addition to setting parameters in the configuration file itself, you can set them at runtime.
Several parameters are only accessed when yt starts up: therefore, if you want to modify any configuration parameters at runtime, you should execute the appropriate commands at the very top of your script!
This involves importing the configuration object and then setting a given parameter to be equal to a specific string. Note that even for items that accept integers, floating points and other non-string types, you must set them to be a string or else the configuration object will consider them broken.
Here is an example script, where we adjust the logging at startup:
import yt yt.set_log_level(1) ds = yt.load("my_data0001") ds.print_stats()
This has the same effect as setting
log_level = 1 in the configuration
file. Note that a log level of 1 means that all log messages are printed to
stdout. To disable logging, set the log level to 50.
Available Configuration Options¶
The following external parameters are available. A number of parameters are used internally.
False): Should logs be colored?
cmyt.arbre): What colormap should be used by default for yt-produced images?
my_plugins.py) The name of our plugin file.
20): What is the threshold (0 to 50) for outputting log files?
/does/not/exist): The default path the
load()function searches for datasets when it cannot find a dataset in the current directory.
True): If true, grid edges for patch AMR datasets will be adjusted such that they fall as close as possible to an integer multiple of the local cell width. If you are working with a dataset with a large number of grids, setting this to False can speed up loading your dataset possibly at the cost of grid-aligned artifacts showing up in slice visualizations.
notebook_password(default: empty): If set, this will be fed to the IPython notebook created by
yt notebook. Note that this should be an sha512 hash, not a plaintext password. Starting
yt notebookwith no setting will provide instructions for setting this.
False): If true, perform automatic object serialization
sketchfab_api_key(default: empty): API key for https://sketchfab.com/ for uploading AMRSurface objects.
False): If true, execution mode will be quiet.
False): If true, logging is directed to stdout rather than stderr
False): If true, automatic caching of datasets is turned off.
/does/not/exist): The default path certain submodules of yt look in for supplemental data files.
Available per-field Plot Options¶
It is possible to customize the default behaviour of plots using per-field configuration.
The default options for plotting a given field can be specified in the configuration file
[plot.field_type.field_name] blocks. The available keys are
yt.default_colormap, see Available Configuration Options): the colormap to use for the field.
True): use a log scale (or symlog if
linthreshis also set).
None): if set to a float different than
True, use a symlog normalization with the given linear threshold.
units(defaults to the units of the field): the units to use to represent the field.
cm): the unit of the integration length when doing e.g. projections. This always has the dimensions of a length. Note that this will only be used if
unitsis also set for the field. The final units will then be
You can also set defaults for all fields of a given field type by omitting the field name, as illustrated below in the deposit block.
[plot.gas.density] cmap = "plasma" log = true units = "mp/cm**3" [plot.gas.velocity_divergence] cmap = "bwr" # use a diverging colormap log = false # and a linear scale [plot.deposit] path_length_units = "kpc" # use kpc for deposition projections
Available per-Field Configuration Options¶
It is possible to set attributes for fields that would typically be set by the frontend source code, such as the aliases for field, the units that field should be expected in, and the display name. This allows individuals to customize what yt expects of a given dataset without modifying the yt source code. For instance, if your dataset has an on-disk field called “particle_extra_field_1” you could specify its units, display name, and what yt should think of it as with:
[fields.nbody.particle_extra_field_1] aliases = ["particle_other_fancy_name", "particle_alternative_fancy_name"] units = "code_time" display_name = "Dinosaurs Density"
Plugin files are a means of creating custom fields, quantities, data objects, colormaps, and other code executable functions or classes to be used in future yt sessions without modifying the source code directly.
To enable a plugin file, call the function
enable_plugins() at the top of your script.
Global system plugin file¶
yt will look for and recognize the file
$HOME/.config/yt/my_plugins.py as a
plugin file. It is possible to rename this file to
plugin_filename in your
yt.toml file, as mentioned above.
You can tell that your system plugin file is being parsed by watching for a logging
message when you import yt. Note that the
yt load command line entry point parses
the plugin file.
Local project plugin file¶
enable_plugins() can be passed an argument to specify
a custom location for a plugin file. This can be useful to define project wise customizations.
In that use case, any system-level plugin file will be ignored.
Plugin File Format¶
Plugin files should contain pure Python code. If accessing yt functions and classes
they will not require the
yt. prefix, because of how they are loaded.
For example, if one created a plugin file containing:
def _myfunc(field, data): return np.random.random(data["density"].shape) add_field( "random", function=_myfunc, sampling_type="cell", dimensions="dimensionless", units="auto", )
then all of my data objects would have access to the field
You can also define other convenience functions in your plugin file. For instance, you could define some variables or functions, and even import common modules:
import os HOMEDIR = "/home/username/" RUNDIR = "/scratch/runs/" def load_run(fn): if not os.path.exists(RUNDIR + fn): return None return load(RUNDIR + fn)
In this case, we’ve written
load_run to look in a specific directory to see
if it can find an output with the given name. So now we can write scripts that
use this function:
import yt yt.enable_plugins() my_run = yt.load_run("hotgasflow/DD0040/DD0040")
And because we have used
yt.enable_plugins we have access to the
load_run function defined in our plugin file.
if your convenience function’s name colliding with an existing object within yt’s namespace, it will be ignored.
Note that using the plugins file implies that your script is no longer fully reproducible. If you share your script with someone else and use some of the functionality if your plugins file, you will also need to share your plugins file for someone else to re-run your script properly.
Adding Custom Colormaps¶
To add custom Colormaps to your plugin file, you must use the
make_colormap() function to generate a
colormap of your choice and then add it to the plugin file. You can see
an example of this in Making and Viewing Custom Colormaps. Remember that you don’t need
to prefix commands in your plugin file with
yt., but you’ll only be
able to access the colormaps when you load the
yt.mods module, not simply