What’s New and Different in yt 3.0?¶
If you are new to yt, welcome! If you’re coming to yt 3.0 from an older version, however, there may be a few things in this version that are different than what you are used to. We have tried to build compatibility layers to minimize disruption to existing scripts, but necessarily things will be different in some ways.
Updating to yt 3.0 from Old Versions (and going back)¶
First off, you need to update your version of yt to yt 3.0. If you’re installing yt for the first time, please visit Getting and Installing yt. If you already have a version of yt installed, you should just need one command:
$ yt update
This will update yt to the most recent version and rebuild the source base. If you installed using the installer script, it will assure you have all of the latest dependencies as well. This step may take a few minutes. To test to make sure yt is running, try:
$ yt --help
If you receive no errors, then you are ready to go. If you have an error, then consult Update errors for solutions.
If you want to switch back to an old version of yt (2.x), see Switching versions of yt: yt-2.x, stable, and master branches.
Converting Old Scripts to Work with yt 3.0¶
After installing yt-3.0, you’ll want to change your old scripts in a few key ways. After accounting for the changes described in the list below, try running your script. If it still fails, the callback failures in python are fairly descriptive and it may be possible to deduce what remaining changes are necessary. If you continue to have trouble, please don’t hesitate to request help.
The list below is arranged in order of most important changes to least important changes.
from yt.mods import *with
import ytand prepend yt classes and functions with
yt.We have reworked yt’s import system so that most commonly-used yt functions and classes live in the top-level yt namespace. That means you can now import yt with
import yt, load a dataset with
ds = yt.load(filename)and create a plot with
yt.SlicePlot. See API Reference for a full API listing. You can still import using
from yt.mods import *to get a pylab-like experience.
Unit conversions are different Fields and metadata for data objects and datasets now have units. The unit system keeps you from making weird things like
gand can handle things like
kg*m/s**2 == Newton. See Symbolic Units and How do I get the convert between code units and physical units for my dataset? for more information.
Change field names from CamelCase to lower_case_with_underscores Previously, yt would use “Enzo-isms” for field names. We now very specifically define fields as lowercase with underscores. For instance, what used to be
VelocityMagnitudewould now be
velocity_magnitude. Axis names are now at the end of field names, not the beginning.
velocity_x. For a full list of all of the fields, see Field List.
Full field names have two parts now Fields can be accessed by a single name, but they are named internally as
(field_type, field_name)for more explicit designation which can address particles, deposited fluid quantities, and more. See Fields in yt.
Code-specific field names can be accessed by the name defined by the external code Mesh fields that exist on-disk in an output file can be read in using whatever name is used by the output file. On-disk fields are always returned in code units. The full field name will be
(code_name, field_name). See Field List.
Particle fields are now more obviously different than mesh fields Particle fields on-disk will also be in code units, and will be named
(particle_type, field_name). If there is only one particle type in the output file, all particles will use
ioas the particle type. See Fields in yt.
dsThe objects we used to refer to as “parameter files” we now refer to as datasets. Instead of
pf, we now suggest you use
dsto refer to an object returned by
Remove any references to
dsYou can now create data objects without referring to the hierarchy. Instead of
pf.h.all_data(), you can now say
ds.all_data(). The hierarchy is still there, but it is now called the index:
yt.enable_parallelism()to make a script parallel-compatible Command line arguments are only parsed when yt is imported using
from yt.mods import *. Since command line arguments are not parsed when using
import yt, it is no longer necessary to specify
--parallelat the command line when running a parallel computation. Use
yt.enable_parallelism()in your script instead. See Parallel Computation With yt for more details.
Change your derived quantities to the new syntax Derived quantities have been reworked. You can now do
dd.quantities['TotalMass'](). See Processing Objects: Derived Quantities.
Change your method of accessing the
gridsattribute of data objects no longer exists. To get this information, you have to use spatial chunking and then access them. See here for an example. For datasets that use grid hierarchies, you can also access the grids for the entire dataset via ds.index.grids. This attribute is not defined for particle or octree datasets.
Cool New Things¶
Lots of new things have been added in yt 3.0! Below we summarize a handful of these.
Lots of New Codes are Supported¶
Because of the additions of Octrees, Particle Deposition, and Irregular Grids, we now support a bunch more codes. See Code Support for more information.
Octree datasets such as RAMSES, ART and ARTIO are now supported – without any regridding! We have a native, lightweight octree indexing system.
MOAB Hex8 format is supported, and non-regular grids can be added relatively easily.
Better Particle Support¶
Particle Codes and SPH¶
yt 3.0 features particle selection, smoothing, and deposition. This utilizes a combination of coarse-grained indexing and octree indexing for particles.
In yt-3.0, we provide mechanisms for describing and creating fields generated by depositing particles into one or a handful of zones. This could include deposited mass or density, average values, and the like. For instance, the total stellar mass in some region can be deposited and averaged.
Particle Filters and Unions¶
Throughout yt, the notion of “particle types” has been more deeply embedded.
These particle types can be dynamically defined at runtime, for instance by
taking a filter of a given type or the union of several different types. This
might be, for instance, defining a new type called
young_stars that is a
star_age to be fewer than a given threshold, or
filters based on the velocity of a particle. Unions could be the joining of
multiple types of particles – the default union of which is
representing all particle types in the simulation.
yt now has a unit system. This is one of the bigger features, and in essence it means that you can convert units between anything. In practice, it makes it much easier to define fields and convert data between different unit systems. See Symbolic Units for more information.
Preliminary support for non-cartesian coordinates has been added. We expect this to be considerably solidified and expanded in yt 3.1.
Reworked Import System¶
It’s now possible to import all yt functionality using
import yt. Rather
from yt.mods import *, we suggest using
import yt in new
scripts. Most commonly used yt functionality is attached to the
Load a dataset with
yt.load(), create a phase plot using
and much more, see the api docs to learn more about what’s
yt namespace, or just use tab completion in IPython:
It’s still possible to use
from yt.mods import * to create an interactive
pylab-like experience. Importing yt this way has several side effects, most
notably the command line arguments parsing and other startup tasks will run.
These are the items that have already changed in user-facing API:
Field naming is probably the single biggest change you will encounter in yt 3.0.
Fields can be accessed by their short names, but yt now has an explicit mechanism of distinguishing between field types and particle types. This is expressed through a two-key description. For example:
will return the gas field density. In this example “gas” is the field type and “density” is the field name. Field types are a bit like a namespace. This system extends to particle types as well. By default you do not need to use the field “type” key, but in case of ambiguity it will utilize the default value in its place. This should therefore be identical to:
To enable a compatibility layer, on the dataset you simply need to call the
setup_deprecated_fields like so:
ds = yt.load("MyData") ds.setup_deprecated_fields()
Units of Fields¶
Fields now are all subclasses of NumPy arrays, the
YTArray, which carries
along with it units. This means that if you want to manipulate fields, you
have to modify them in a unitful way. See Symbolic Units.
Parameter Files are Now Datasets¶
Wherever possible, we have attempted to replace the term “parameter file”
pf) with the term “dataset.” In yt-3.0, all of
pf attributes of objects are now
Hierarchy is Now Index¶
The hierarchy object (
pf.h) is now referred to as an index (
It is no longer necessary to directly refer to the
index as often, since
data objects are now attached to the to the
dataset object. Before, you
pf.h.sphere(), now you can say
New derived quantities interface¶
Derived quantities can now be accessed via a function that hangs off of the
quantities attribute of data objects. Instead of
dd.quantities['TotalMass'](), you can now use
to do the same thing. All derived quantities can be accessed via a function that
hangs off of the quantities attribute of data objects.
Any derived quantities that always returned lists (like
would return a list even if you only ask for one field) now only returns a
single result if you only ask for one field. Results for particle and mesh
fields will also be returned separately. See Processing Objects: Derived Quantities for more
In previous versions of yt, the
dataset object (what we used to call a
parameter file) had a
field_info attribute which was a dictionary leading to
derived field definitions. At the present time, because of the field naming
changes (i.e., access-by-tuple) it is better to utilize the function
_get_field_info than to directly access the
field_info dictionary. For
finfo = ds._get_field_info("gas", "density")
This function respects the special “field type”
unknown and will search all
field types for the field name.
Projection Argument Order¶
Previously, projections were inconsistent with the other data objects.
(The API for Plot Windows is the same.) The argument order is now
axis as seen here:
All data objects now accept an explicit list of
kwargs and supplying them to field parameters. See
Nearly all internal objects have been renamed. Typically this means either
AMR from the prefix or replacing it with
YT. All names of
objects remain the same for the purposes of selecting data and creating them;
sphere objects are still called
sphere - you can access or create one
ds.sphere. For a detailed description and index see
Boolean regions are not yet implemented in yt 3.0.
It used to be that one could get access to the grids that belonged to a data
object. Because we no longer have just grid-based data in yt, this attribute
does not make sense. If you need to determine which grids contribute to a
given object, you can either query the
grid_indices field, or mandate
spatial chunking like so:
for chunk in obj.chunks(, "spatial"): for grid in chunk._current_chunk.objs: print(grid)
This will “spatially” chunk the
obj object and print out all the grids
Halo Profiler infrastructure has been fundamentally rewritten and now
exists using the
Halo Catalog framework. See Halo Analysis.
While we’re trying to port over all of the old analysis modules, we have not gotten all of them working in 3.0 yet. The docs pages for those modules not-yet-functioning are clearly marked.