Command-Line Usage¶

Command-line Functions¶

The yt command-line tool allows you to access some of yt’s basic functionality without opening a python interpreter. The tools is a collection of subcommands. These can quickly making plots of slices and projections through a dataset, updating yt’s codebase, print basic statistics about a dataset, launch an IPython notebook session, and more. To get a quick list of what is available, just type:

yt -h

This will print the list of available subcommands,

help                Print help message
instinfo            Get some information about the yt installation
version             Get some information about the yt installation
load                Load a single dataset into an IPython instance
mapserver           Serve a plot in a GMaps-style interface
pastebin            Post a script to an anonymous pastebin
pastebin_grab       Print an online pastebin to STDOUT for local use.
plot                Create a set of images
rpdb                Connect to a currently running (on localhost) rpd
                    session. Commands run with --rpdb will trigger an rpdb
                    session with any uncaught exceptions.
stats               Print stats and max/min value of a given field (if
                    requested), for one or more datasets (default field is
                    density)
update              Update the yt installation to the most recent version
delete_image        Delete image from imgur.com.
upload_image        Upload an image to imgur.com. Must be PNG.
upload              Upload a file to yt's curldrop.
config              Get and set configuration values for yt
search              Attempt to find outputs that yt can recognize in
                    directories.
download            Download a file from http://yt-project.org/data and
                    save it to a particular location. Files can be saved
                    to the locations provided by the "test_data_dir" or
                    "supp_data_dir" configuration entries, or any valid
                    path to a location on disk.

To execute any such function, simply run:

yt <subcommand>

Finally, to identify the options associated with any of these subcommand, run:

yt <subcommand> -h

Plotting from the command line¶

First, we’ll discuss plotting from the command line, then we will give a brief summary of the functionality provided by each command line subcommand. This example uses the DD0010/moving7_0010 dataset distributed in the yt git repository.

First let’s see what our options are for plotting:

$ yt plot --help

There are many! We can choose whether we want a slice (default) or a projection (-p), the field, the colormap, the center of the image, the width and unit of width of the image, the limits, the weighting field for projections, and on and on. By default the plotting command will execute the same thing along all three axes, so keep that in mind if it takes three times as long as you’d like! The center of a slice defaults to the center of the domain, so let’s just give that a shot and see what it looks like:

$ yt plot DD0010/moving7_0010

Well, that looks pretty bad! What has happened here is that the center of the domain only has some minor shifts in density, so the plot is essentially incomprehensible. Let’s try it again, but instead of slicing, let’s project. This is a line integral through the domain, and for the density field this becomes a column density:

$ yt plot -p DD0010/moving7_0010

Now that looks much better! Note that all three axes’ projections appear nearly indistinguishable, because of how the two spheres are located in the domain. We could center our domain on one of the spheres and take a slice, as well. Now let’s see what the domain looks like with grids overlaid, using the --show-grids option:

$ yt plot --show-grids -p DD0010/moving7_0010

We can now see all the grids in the field of view. If you want to annotate your plot with a scale bar, you can use the --show-scale-bar option:

$ yt plot --show-scale-bar -p DD0010/moving7_0010

Command-line subcommand summary¶

help¶

Help lists all of the various command-line options in yt.

instinfo and version¶

This gives information about where your yt installation is, what version and changeset you’re using and more.

mapserver¶

Ever wanted to interact with your data using a google maps-style interface? Now you can by using the yt mapserver. See Mapserver - A Google-Maps-like Interface to your Data for more details.

pastebin and pastebin_grab¶

The pastebin is an online location where you can anonymously post code snippets and error messages to share with other users in a quick, informal way. It is often useful for debugging code or co-developing. By running the pastebin subcommand with a text file, you send the contents of that file to an anonymous pastebin;

yt pastebin my_script.py

By running the pastebin_grab subcommand with a pastebin number (e.g. 1768), it will grab the contents of that pastebin (e.g. the website http://paste.yt-project.org/show/1768 ) and send it to STDOUT for local use. See Pastebin for more information.

yt pastebin_grab 1768

upload¶

Upload a file to a public curldrop instance. Curldrop is a simple web application that allows you to upload and download files straight from your Terminal with an http client like e.g. curl. It was initially developed by Kevin Kennell and later forked and adjusted for yt’s needs. After a successful upload you will receive a url that can be used to share the data with other people.

yt upload my_file.tar.gz

plot¶

This command generates one or many simple plots for a single dataset. By specifying the axis, center, width, etc. (run yt help plot for details), you can create slices and projections easily at the command-line.

rpdb¶

Connect to a currently running (on localhost) rpdb session. See Remote and Disconnected Debugging for more info.

notebook¶

Launches a Jupyter notebook server and prints out instructions on how to open an ssh tunnel to connect to the notebook server with a web browser. This is most useful when you want to run a Jupyter notebook using CPUs on a remote host.

stats¶

This subcommand provides you with some basic statistics on a given dataset. It provides you with the number of grids and cells in each level, the time of the dataset, and the resolution. It is tantamount to calling the Dataset.print_stats method.

Additionally, there is the option to print the minimum, maximum, or both for a given field. The field is assumed to be density by default:

yt stats GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0150 --max --min

or a different field can be specified using the -f flag:

yt stats GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0150 --max --min -f gas,temperature

The field-related stats output from this command can be directed to a file using the -o flag:

yt stats GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0150 --max -o out_stats.dat

update¶

This subcommand updates the yt installation to the most recent version for your repository (e.g. stable, 2.0, development, etc.). Adding the --all flag will update the dependencies as well.

upload_image¶

Images are often worth a thousand words, so when you’re trying to share a piece of code that generates an image, or you’re trying to debug image-generation scripts, it can be useful to send your co-authors a link to the image. This subcommand makes such sharing a breeze. By specifying the image to share, upload_image automatically uploads it anonymously to the website imgur.com and provides you with a link to share with your collaborators. Note that the image must be in the PNG format in order to use this function.

delete_image¶

The image uploaded using upload_image is assigned with a unique hash that can be used to remove it. This subcommand provides an easy way to send a delete request directly to the imgur.com.

download¶

This subcommand downloads a file from https://yt-project.org/data. Using yt download, one can download a file to:

"test_data_dir": Save the file to the location specified in the "test_data_dir" configuration entry for test data.
"supp_data_dir": Save the file to the location specified in the "supp_data_dir" configuration entry for supplemental data.
Any valid path to a location on disk, e.g. /home/jzuhone/data.

Examples:

$ yt download apec_emissivity_v2.h5 supp_data_dir

$ yt download GasSloshing.tar.gz test_data_dir

$ yt download ZeldovichPancake.tar.gz /Users/jzuhone/workspace

If the configuration values "test_data_dir" or "supp_data_dir" have not been set by the user, an error will be thrown.

Config helper¶

The yt config command-line tool allows you to modify and access yt’s configuration without manually locating and opening the config file in an editor. To get a quick list of available commands, just type:

yt config -h

This will print the list of available subcommands:

get                 get a config value
set                 set a config value
rm                  remove a config option
list                show the config content
print-path          show path to the config file

Since yt version 4, the configuration file is located in $XDG_CONFIG_HOME/yt/yt.toml adhering to the XDG Base Directory Specification. Unless customized, this defaults to $HOME/.config/ on Unix-like systems (macOS, Linux, …). The old configuration file ($XDG_CONFIG_HOME/yt/ytrc) is deprecated. In order to perform an automatic migration of the old config, you are encouraged to run:

yt config migrate

This will convert your old config file to the toml format. The original file will be moved to $XDG_CONFIG_HOME/yt/ytrc.bak.

Examples¶

Listing current content of the config file:

$ yt config list
[yt]
log_level = 50

Obtaining a single config value by name:

$ yt config get yt log_level
50

Changing a single config value:

$ yt config set yt log_level 10

Removing a single config entry:

$ yt config rm yt log_level