|
@@ -188,6 +178,7 @@ Table of Contents
intro/index
installing
yt Quickstart
+ yt4differences
yt3differences
cookbook/index
visualizing/index
@@ -195,7 +186,6 @@ Table of Contents
analyzing/domain_analysis/index
examining/index
developing/index
- sharing_data
reference/index
faq/index
Getting Help
diff --git a/doc/source/installing.rst b/doc/source/installing.rst
index c743d4283bb..59aeec7f87c 100644
--- a/doc/source/installing.rst
+++ b/doc/source/installing.rst
@@ -1,4 +1,4 @@
-.. _getting-and-installing-yt:
+.. _installing-yt:
Getting and Installing yt
=========================
@@ -10,589 +10,228 @@ Getting and Installing yt
.. _getting-yt:
-Getting yt
+Disclaimer
----------
-In this document we describe several methods for installing yt. The method that
-will work best for you depends on your precise situation:
-
-* If you do not have root access on your computer, are not comfortable managing
- python packages, or are working on a machine where you are not allowed to, you
- will probably want to use the bash all-in-one installation script. This
- creates a python environment using the `miniconda python
- distribution `_ and the
- `conda `_ package manager inside of a single
- folder in your home directory. See :ref:`install-script` for more details.
-
-* If you use the `Anaconda `_ python
- distribution and already have ``conda`` installed, see
- :ref:`anaconda-installation` for details on how to install yt using the
- ``conda`` package manager. Note that this is currently the only supported
- installation mechanism on Windows.
-
-* A viable alternative to the installation based on Anaconda is the use of the
- `Intel Distribution for Python `_.
- For `Parallel Computation `_
- on Intel architectures, especially on supercomputers, a large
- `performance and scalability improvement `_
- over several common tasks has been demonstrated.
- Detailed installation instructions are provided below as well, see :ref:`conda-intel-python`.
- No change in the way yt is managed by ``conda`` is required.
-
-* Some operating systems have ``yt`` pre-built packages that can be
- installed with the system package manager. Note that the packages in some of
- these distributions may not be the most recent release. See :ref:`distro-packages`
- for a list of available packages. You can always get the current stable
- version of ``yt`` via ``conda`` as described in :ref:`anaconda-installation`
- or via ``pip`` as described in :ref:`source-installation`.
-
-* If you want to build a development version of yt or are comfortable with
- compilers and know your way around python packaging,
- :ref:`source-installation` will probably be the best choice. If you have set
- up python using a source-based package manager like `Homebrew
- `_ or `MacPorts `_ this choice will
- let you install yt using the python installed by the package
- manager. Similarly, this will also work for python environments set up via
- Linux package managers so long as you have the necessary compilers installed
- (e.g. the ``build-essentials`` package on Debian and Ubuntu).
+The Python ecosystem offers many viable tools to setup isolated
+Python environments, including but not restricted to
-.. note::
- See `Parallel Computation
- `_
- for a discussion on using yt in parallel.
+- `venv `_ (part of the Python standard library)
+- `Anaconda/conda `_
+- `virtualenv `_
-.. _branches-of-yt:
+We strongly recommend you choose and learn one. However, it is beyond the
+scope of this page to cover every situation.
-Branches of yt: ``main``, ``stable``, and ``yt-2.x``
-++++++++++++++++++++++++++++++++++++++++++++++++++++++
+We will show you how to install a stable release or from source, using conda
+or pip, and we will *assume* that you do so in an isolated environment.
-Before you install yt, you must decide which branch (i.e. version) of the code
-you prefer to use:
+Also note that each yt release supports a limited range of Python versions.
+Here's a summary for most recent releases
-* ``main`` -- The most up-to-date *development* version with the most current
- features but sometimes unstable (the development version of the next release).
-* ``stable`` -- The latest stable release of ``yt-3.x``.
-* ``yt-2.x`` -- The last stable release of ``yt-2.x``.
++------------+------------+----------------------------------+
+| yt release | Python 2.7 | Python3 min | Python3 max |
++============+============+================+=================+
+| 4.1.x | no | 3.7 (expected) | 3.10 (expected) |
++------------+------------+----------------+-----------------+
+| 4.0.x | no | 3.6 | 3.9 |
++------------+------------+----------------+-----------------+
+| 3.6.x | no | 3.5 | 3.8 |
++------------+------------+----------------+-----------------+
+| 3.5.x | yes | 3.4 | 3.5 |
++------------+------------+----------------+-----------------+
-If this is your first time using the code, we recommend using ``stable``, unless
-you specifically need some piece of brand-new functionality only available in
-``main`` or need to run an old script developed for ``yt-2.x``. There were major
-API and functionality changes made in yt for version 3.0. For a detailed
-description of the changes between versions 2.x (e.g. branch ``yt-2.x``) and 3.x
-(e.g. branches ``main`` and ``stable``) see :ref:`yt3differences`. Lastly, don't
-feel like you're locked into one branch when you install yt, because you can
-easily change the active branch by following the instructions in
-:ref:`switching-between-yt-versions`.
+Where the Python3 max column is purely indicative and reflects the newest
+*guaranteed* compatible version.
-.. _install-script:
-All-in-One Installation Script
-++++++++++++++++++++++++++++++
+Getting yt
+----------
-Because installation of all of the interlocking parts necessary to install yt
-itself can be time-consuming, yt provides an all-in-one installation script
-which downloads and builds a fully-isolated installation of Python that includes
-NumPy, Matplotlib, H5py, git, and yt.
+In this document we describe several methods for installing yt. The method that
+will work best for you depends on your precise situation:
-The install script supports UNIX-like systems, including Linux, OS X, and most
-supercomputer and cluster environments. It is particularly suited for deployment
-in environments where users do not have root access and can only install
-software into their home directory.
+* If you need a stable build, see :ref:`install-stable`
-Since the install is fully-isolated in a single directory, if you get tired of
-having yt on your system, you can just delete the directory and yt and all of
-its dependencies will be removed from your system (no scattered files remaining
-throughout your system).
+* If you want to build the development version of yt see :ref:`install-from-source`.
-.. _installing-yt:
+.. _install-stable:
-Running the Install Script
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Installing a stable release
++++++++++++++++++++++++++++
-You can download the installation script with the following command:
+The latest stable release can be obtained from Pypi with pip
.. code-block:: bash
- $ wget https://raw.githubusercontent.com/yt-project/yt/main/doc/install_script.sh
-
-If you do not have ``wget``, the following should also work:
+ $ python -m pip install --upgrade pip
+ $ python -m pip install --user yt
-.. code-block:: bash
- $ curl -OL https://raw.githubusercontent.com/yt-project/yt/main/doc/install_script.sh
-
-By default, the bash install script will create a python environment based on
-the `miniconda python distribution `_,
-and will install yt's dependencies using the `conda
-`_ package manager. To avoid needing a
-compilation environment to run the install script, yt itself will also be
-installed using ``conda``.
-
-If you would like to customize your yt installation, you can edit the values of
-several variables that are defined at the top of the script.
-
-If you would like to build yt from source, you will need to edit the install
-script and set ``INST_YT_SOURCE=1`` near the top. This will clone a copy of the
-yt git repository and build yt form source. The default is
-``INST_YT_SOURCE=0``, which installs yt from a binary conda package.
-
-In addition, you can tell the install script to download and install some
-additional packages --- currently these include
-`PyX `_, the `Rockstar halo
-finder `_, `SciPy `_,
-`Astropy `_,
-`Cartopy `_,
-and the necessary dependencies for
-:ref:`unstructured mesh rendering `. The script has
-all of the options for installing optional packages near the top of the
-file. You should be able to open it and edit it without any knowledge of bash
-syntax. For example, to install scipy, change ``INST_SCIPY=0`` to
-``INST_SCIPY=1``.
-
-To execute the install script, run:
+Or using the Anaconda/Miniconda Python distributions
.. code-block:: bash
- $ bash install_script.sh
-
-Because the installer is downloading and building a variety of packages from
-source, this will likely take a few minutes, especially if you have a slow
-internet connection. You will get updates of its status at the command prompt
-throughout.
-
-If you receive errors during this process, the installer will provide you
-with a large amount of information to assist in debugging your problems. The
-file ``yt_install.log`` will contain all of the ``stdout`` and ``stderr`` from
-the entire installation process, so it is usually quite cumbersome. By looking
-at the last few hundred lines (i.e. ``tail -500 yt_install.log``), you can
-potentially figure out what went wrong. If you have problems, though, do not
-hesitate to :ref:`contact us ` for assistance.
+ $ conda install --channel conda-forge yt
-.. _activating-yt:
-Activating Your Installation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _install-from-source:
-Once the installation has completed, there will be instructions on how to set up
-your shell environment to use yt.
+Building from source
+++++++++++++++++++++
-In particular, you will need to ensure that the installation's ``yt-conda/bin``
-directory is prepended to your ``PATH`` environment variable.
+To build yt from source, you need ``git``, and a C compiler (such as ``gcc``
+or ``clang``).
-For Bash-style shells, you can use the following command in a terminal session
-to temporarily activate the yt installation:
+Then run
.. code-block:: bash
- $ export PATH=/path/to/yt-conda/bin:$PATH
-
-and on csh-style shells:
-
-.. code-block:: csh
+ $ git clone https://github.com/yt-project/yt
+ $ cd yt
+ $ python -m pip install --upgrade pip
+ $ python -m pip install --user -e .
- $ setenv PATH /path/to/yt-conda/bin:$PATH
-If you would like to permanently activate yt, you can also update the init file
-appropriate for your shell and OS (e.g. .bashrc, .bash_profile, .cshrc, .zshrc)
-to include the same command.
+.. _optional-runtime-deps:
-.. _updating-yt:
+Leveraging optional yt runtime dependencies
++++++++++++++++++++++++++++++++++++++++++++
-Updating yt and Its Dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Some relatively heavy runtime dependencies are not included in your build by
+default as they may be irrelevant in your workflow. Common examples include
+h5py, mpi4py, astropy or scipy. yt implements a on-demand import mechanism that
+allows it to run even when they are not installed *until they're needed*, in
+which case it will raise an ``ImportError``, pointing to the missing requirement.
-With many active developers, code development sometimes occurs at a furious
-pace in yt. To make sure you're using the latest version of the code, run
-this command at a command-line:
+If you wish to get everything from the start, you may specify it when building
+yt as by appending ``[full]`` to the target name when calling pip, i.e.,
.. code-block:: bash
- $ conda update yt
+ $ # stable release
+ $ python -m pip install --user yt[full]
+ $ # from source
+ $ python -m pip install --user -e .[full]
-If you want to update your dependencies, run:
-.. code-block:: bash
+.. _testing-installation:
- $ conda update --all
+Testing Your Installation
++++++++++++++++++++++++++
-If you have installed yt from source, you can use the following command to get
-the latest development version of yt:
+To test to make sure everything is installed properly, try running yt at
+the command line:
.. code-block:: bash
- $ yt update
+ $ python -c "import yt"
-.. _removing-yt:
+If this runs without raising errors, you have successfully installed yt. Congratulations!
-Removing yt and Its Dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Otherwise, read the error message carefully and follow any instructions it gives
+you to resolve the issue. Do not hesitate to :ref:`contact us `
+so we can help you figure it out.
-Because yt and its dependencies are installed in an isolated directory when
-you use the script installer, you can easily remove yt and all of its
-dependencies cleanly. Simply remove the install directory and its
-subdirectories::
- $ rm -rf yt-conda
-If you *really* had problems with the installation process, this is a last
-defense for solving: remove and then fully :ref:`re-install `
-from the install script again.
+.. _updating:
-.. _anaconda-installation:
+Updating yt
++++++++++++
-Installing yt Using Anaconda
-++++++++++++++++++++++++++++
-
-For both the Anaconda and Miniconda installations, make sure that the Anaconda
-``bin`` directory is in your path, and then issue:
+For pip-based installations:
.. code-block:: bash
- $ conda install -c conda-forge yt
-
-which will install stable branch of yt along with all of its dependencies.
-
-.. _conda-intel-python:
+ $ python -m pip install --upgrade yt
-Using the Intel Distribution for Python from conda
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you use conda, you can install yt with the
-`Intel Distribution for Python `_
-(recommended for performance in parallel computations on Intel architectures) instead of
-the standard Anaconda distribution. First you need to add the intel channel:
+For conda-based installations:
.. code-block:: bash
- $ conda config --add channels intel
-
-If you want, at this point you can create a separate environment and switch to it:
-
-.. code-block:: bash
-
- $ conda create -c intel -n yt_intel
- $ conda activate yt_intel
-
-Now you need to install the remaining yt dependencies in your current environment.
-The following provides the Intel-optimized versions of these underlying packages:
-
-.. code-block:: bash
-
- $ conda config --add channels intel
- $ conda install -c intel numpy scipy mpi4py cython git sympy ipython matplotlib netCDF4
-
-Then you can install yt normally, either from the conda-forge channel as above, or from source (see below).
-
-.. _distro-packages:
-
-yt Distribution Packages
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note::
-
- Since the third-party packages listed below are not officially supported by
- yt developers, support should not be sought out on the project mailing lists
- or Slack channels. All support requests related to these packages should be
- directed to their official maintainers.
-
-While we recommended installing ``yt`` with either the ``conda`` or ``pip``
-package managers, a number of third-party packages exist for the distributions
-listed below. If you can't find your distro here, you can always install
-``yt``'s current stable version using ``conda`` or ``pip``, or build the latest
-development version from source.
-
-.. image:: https://repology.org/badge/vertical-allrepos/python:yt.svg?header=yt%20packaging%20status
- :target: https://repology.org/project/python:yt/versions
-
-.. note::
-
- Please be aware that the packages in some of these distributions may be out-of-date!
-
-.. _conda-source-build:
-
-Building yt from Source For Conda-based Installs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-First, ensure that you have all build dependencies installed in your current
-conda environment:
-
-.. code-block:: bash
-
- $ conda install -c conda-forge cython git sympy ipython matplotlib netCDF4
-
-In addition, you will need a C compiler installed.
-
-Clone the yt repository with:
-
-.. code-block:: bash
+ $ conda update yt
- $ git clone https://github.com/yt-project/yt
-Once inside the yt directory, update to the appropriate branch and run
-``pip install -e .``. For example, the following commands will allow
-you to see the tip of the development branch.
+For git-based installations (yt installed from source), we provide the following
+one-liner facility
.. code-block:: bash
- $ git checkout main
- $ pip install -e .
-
-This will make sure you are running a version of yt corresponding to the
-most up-to-date source code.
-
-.. note::
-
- Alternatively, you can replace ``pip install -e .`` with ``conda develop -b .``.
-
-.. _windows-installation:
-
-Installing yt on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Installation on 64-bit Microsoft Windows platforms is supported using Anaconda
-(see :ref:`anaconda-installation`) and via ``pip``.
-
-.. _source-installation:
-
-Installing yt Using ``pip``
-+++++++++++++++++++++++++++
-
-If you already have a python installation that you manage using ``pip`` you can
-install the latest release of yt by doing::
-
- $ pip install yt
-
-If you do not have root access you may need to append ``--user`` to install to a
-location in your home folder.
-
-Installing yt from source
-+++++++++++++++++++++++++
-
-.. note::
+ $ yt update
- If you wish to install yt from source in a conda-based installation of yt,
- see :ref:`conda-source-build`.
+This will pull any changes from GitHub, and recompile yt if necessary.
-To install yt from source, you must make sure you have yt's dependencies
-installed on your system. Right now, the dependencies to build yt from
-source include:
-- ``git``
-- A C compiler such as ``gcc`` or ``clang``
-- ``Python >= 3.6``
+Uninstalling yt
++++++++++++++++
-In addition, building yt from source requires ``numpy`` and ``cython``
-which can be installed with ``pip``:
+If you've installed via pip (either from Pypi or from source)
.. code-block:: bash
- $ pip install --upgrade numpy cython
-
-You may also want to install some of yt's optional dependencies, including
-``jupyter``, ``h5py`` (which in turn depends on the HDF5 library), ``scipy``,
-``astropy``, or ``cartopy``.
+ $ python -m pip uninstall yt
-The source code for yt may be found on GitHub. If you prefer to install the
-development version of yt instead of the latest stable release, you will need
-``git`` to clone the official repo:
+Or with conda
.. code-block:: bash
- $ git clone https://github.com/yt-project/yt
- $ cd yt
- $ git checkout main
- $ pip install . --user --install-option="--prefix="
-
-.. note::
+ $ conda uninstall yt
- If you maintain your own user-level python installation separate from the
- OS-level python installation, you can leave off ``--user --install-option="--prefix="``, although
- you might need ``sudo`` depending on where python is installed. See `This
- StackOverflow discussion
- `_
- if you are curious why ``--install-option="--prefix="`` is necessary on some systems.
-This will install yt into a folder in your home directory
-(e.g. ``$HOME/.local/lib64/python/site-packages`` on Linux,
-``$HOME/Library/Python//lib/python/site-packages/`` on OSX) Please refer to
-the ``setuptools`` documentation for the additional options.
+TroubleShooting
+---------------
-If you are unable to locate the ``yt`` executable (i.e. executing ``yt version``
+If you are unable to locate the yt executable (i.e. executing ``yt version``
at the bash command line fails), then you likely need to add the
``$HOME/.local/bin`` (or the equivalent on your OS) to your PATH. Some Linux
distributions do not include this directory in the default search path.
-If you choose this installation method, you do not need to run any activation
-script since this will install yt into your global python environment.
-
-If you will be modifying yt, you can also make the clone of the yt git
-repository the "active" installed copy:
-
-.. code-block:: bash
-
- $ git clone https://github.com/yt-project/yt
- $ cd yt
- $ git checkout main
- $ pip install -e . --user --install-option="--prefix="
-
-As above, you can leave off ``--user --install-option="--prefix="`` if you want to install yt into
-the default package install path. If you do not have write access for this
-location, you might need to use ``sudo``.
-
-Build errors with ``setuptools`` or ``distribute``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Building yt requires version 18.0 or higher of ``setuptools``. If you see error
-messages about this package, you may need to update it. For example, with pip
-via
-
-.. code-block:: bash
-
- $ pip install --upgrade setuptools
-
-or your preferred method. If you have ``distribute`` installed, you may also see
-error messages for it if it's out of date. You can update with pip via
-
-.. code-block:: bash
-
- $ pip install --upgrade distribute
-
-or via your preferred method.
-
-Keeping yt Updated via Git
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you want to maintain your yt installation via updates straight from the
-GitHub repository or if you want to do some development on your own, we
-suggest you check out some of the :ref:`development docs `,
-especially the sections on :ref:`Git ` and
-:ref:`building yt from source `.
-
-You can also make use of the following command to keep yt up to date from the
-command line:
-
-.. code-block:: bash
-
- $ yt update
-
-This will detect that you have installed yt from the git repository, pull any
-changes from GitHub, and then recompile yt if necessary.
-
-.. _testing-installation:
-
-Testing Your Installation
--------------------------
-
-To test to make sure everything is installed properly, try running yt at
-the command line:
-
-.. code-block:: bash
-
- $ yt --help
-
-If this works, you should get a list of the various command-line options for
-yt, which means you have successfully installed yt. Congratulations!
-
-If you get an error, follow the instructions it gives you to debug the problem.
-Do not hesitate to :ref:`contact us ` so we can help you
-figure it out. There is also information at :ref:`update-errors`.
-
-If you like, this might be a good time to run the test suite, see :ref:`testing`
-for more details.
-
-.. _switching-between-yt-versions:
-
-Switching versions of yt: ``yt-2.x``, ``stable``, and ``main`` branches
--------------------------------------------------------------------------
-
-Here we explain how to switch between different development branches of yt.
-
-If You Installed yt Using the Bash Install Script
-+++++++++++++++++++++++++++++++++++++++++++++++++
-
-The instructions for how to switch between branches depend on whether you ran
-the install script with ``INST_YT_SOURCE=0`` (the default) or
-``INST_YT_SOURCE=1``. You can determine which option you used by inspecting the
-output:
-
-.. code-block:: bash
-
- $ yt version
-
-If the output from this command looks like:
-
-.. code-block:: none
-
- The current version and changeset for the code is:
-
- ---
- Version = 3.2.3
- ---
-
-i.e. it does not refer to a specific changeset hash, then you originally chose
-``INST_YT_SOURCE=0``.
-
-On the other hand, if the output from ``yt version`` looks like:
-
-.. code-block:: none
- The current version and changeset for the code is:
+Additional Resources
+--------------------
- ---
- Version = 3.3-dev
- Changeset = d8eec89b2c86
- ---
-
-i.e. it refers to a specific changeset in the yt git repository, then
-you installed using ``INST_YT_SOURCE=1``.
-
-Conda-based installs (``INST_YT_SOURCE=0``)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In this case you can follow the instructions above to build yt from source under conda (see
-:ref:`conda-source-build`).
-
-Source-based installs (``INST_YT_SOURCE=1``)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You already have the git repository, so you simply need to switch
-which version you're using. Navigate to the root of the yt git
-repository, check out the desired version, and rebuild the source (some of the
-C code requires a compilation step for big changes like this):
+.. _distro-packages:
-.. code-block:: bash
+yt Distribution Packages
+++++++++++++++++++++++++
- $ cd yt-/src/yt-git
- $ git checkout
- $ pip install -e .
+Some operating systems have yt pre-built packages that can be installed with the
+system package manager. Note that the packages in some of these distributions
+may be out of date.
-Valid versions to jump to are described in :ref:`branches-of-yt`.
+.. note::
-You can check which version of yt you have installed by invoking ``yt version``
-at the command line. If you encounter problems, see :ref:`update-errors`.
+ Since the third-party packages listed below are not officially supported by
+ yt developers, support should not be sought out on the project mailing lists
+ or Slack channels. All support requests related to these packages should be
+ directed to their official maintainers.
-If You Installed yt Using from Source or Using pip
-++++++++++++++++++++++++++++++++++++++++++++++++++
+While we recommended installing yt with either pip or conda, a number of
+third-party packages exist for the distributions listed below.
-If you have installed python via ``pip``, remove
-any extant installations of yt on your system and clone the git
-repository of yt as described in :ref:`source-installation`.
+.. image:: https://repology.org/badge/vertical-allrepos/python:yt.svg?header=yt%20packaging%20status
+ :target: https://repology.org/project/python:yt/versions
-.. code-block:: bash
- $ pip uninstall yt
- $ git clone https://github.com/yt-project/yt
+Intel distribution for Python
++++++++++++++++++++++++++++++
-Now, to switch between versions, you need to navigate to the root of the git yt
-repository. Use git to update to the appropriate version and recompile.
+A viable alternative to the installation based on Anaconda is the use of the
+`Intel Distribution for Python
+`_. For `Parallel
+Computation
+`_ on Intel
+architectures, especially on supercomputers, a large `performance and
+scalability improvement `_ over several common
+tasks has been demonstrated. See `Parallel Computation
+`_ for a
+discussion on using yt in parallel. Leveraing this specialized distribution for
+yt requires that you install some dependencies from the intel conda channel
+before installing yt itself, like so
.. code-block:: bash
- $ cd yt
- $ git checkout
- $ pip install . --user --install-option="--prefix="
-
-Valid versions to jump to are described in :ref:`branches-of-yt`).
-
-You can check which version of yt you have installed by invoking ``yt version``
-at the command line. If you encounter problems, see :ref:`update-errors`.
+ $ conda install -c intel numpy scipy mpi4py cython git sympy ipython matplotlib netCDF4
+ $ python -m install --user yt
diff --git a/doc/source/intro/index.rst b/doc/source/intro/index.rst
index 22f3c4a6175..eb8648ab649 100644
--- a/doc/source/intro/index.rst
+++ b/doc/source/intro/index.rst
@@ -37,8 +37,7 @@ cylinders), based on :ref:`field values ` (e.g. all gas >
10^6 K), or for :ref:`constructing new data products `
(e.g. projections, slices, isosurfaces). Furthermore, yt can calculate
the :ref:`bulk quantities ` associated with these data
-objects (e.g. total mass, bulk velocity, angular momentum) or you can
-:ref:`define your own `.
+objects (e.g. total mass, bulk velocity, angular momentum).
General Analysis
^^^^^^^^^^^^^^^^
@@ -56,8 +55,7 @@ processors simultaneously `.
Datasets can be analyzed by simply :ref:`examining raw source data
`, or they can be processed in a number of ways
to extract relevant information and to explore the data including
-:ref:`visualizing data ` and employing :ref:`topic-specific
-analysis modules `.
+:ref:`visualizing data `.
Visualization
^^^^^^^^^^^^^
@@ -96,30 +94,6 @@ renderings `, and :ref:`visualizing isosurfaces in an external
interactive tool `. yt even has a special web-based tool for
exploring your data with a :ref:`google-maps-like interface `.
-Topic-Specific Analysis Modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Beyond visualization and general analysis tools, yt contains a number
-of :ref:`topic-specific analysis modules ` for processing
-datasets. These analysis modules operate somewhat autonomous and oftentimes
-use external libraries or codes. While they are installed with yt, they are
-not loaded by default in every session so you have to call them specifically.
-Examples include :ref:`halo analysis ` (including
-:ref:`halo finding `, :ref:`merger trees `,
-:ref:`halo mass functions `), :ref:`synthetic observations
-` (including :ref:`cosmological light cones
-`, :ref:`cosmological light rays `,
-:ref:`synthetic absorption spectra `, :ref:`spectral
-emission distributions (SEDS) `, :ref:`star formation
-rates `, :ref:`synthetic x-ray observations
-`, and :ref:`synthetic sunyaev-zeldovich effect
-observations `), :ref:`two-point correlations functions
-`, :ref:`identification of overdensities in arbitrary
-fields (clump finding) `, :ref:`tracking particle trajectories
-`, and exporting data to external radiative transfer
-codes (e.g. :ref:`Sunrise ` and :ref:`RadMC-3D
-`).
-
Executing and Scripting yt
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -157,8 +131,7 @@ like you to support it, add code, add documentation, etc. As such, we welcome
members of the public to join :ref:`our community ` by contributing
code, bug reports, documentation, and helping to :ref:`support the code in a
number of ways `. Sooner or later, you'll want to
-:ref:`add your own derived field `, :ref:`derived
-quantity `, :ref:`data object
+:ref:`add your own derived field `, :ref:`data object
`, :ref:`code frontend ` or :ref:`make
yt compatible with an external code `. We have
detailed instructions on how to :ref:`contribute code `
@@ -176,7 +149,7 @@ problems.
Getting Started
^^^^^^^^^^^^^^^
-We have detailed :ref:`installation instructions `
+We have detailed :ref:`installation instructions `
and support for a number of platforms including Unix, Linux, MacOS, and
Windows. If you are new to yt, check out the :ref:`yt Quickstart
` and the :ref:`cookbook ` for a demonstration of yt's
diff --git a/doc/source/quickstart/4)_Data_Objects_and_Time_Series.ipynb b/doc/source/quickstart/4)_Data_Objects_and_Time_Series.ipynb
index ed5f560e2d2..785031cef84 100644
--- a/doc/source/quickstart/4)_Data_Objects_and_Time_Series.ipynb
+++ b/doc/source/quickstart/4)_Data_Objects_and_Time_Series.ipynb
@@ -6,7 +6,7 @@
"source": [
"# Data Objects and Time Series Data\n",
"\n",
- "Just like before, we will load up yt. Since we'll be using pylab to plot some data in this notebook, we additionally tell matplotlib to place plots inline inside the notebook."
+ "Just like before, we will load up yt. Since we'll be using pyplot to plot some data in this notebook, we additionally tell matplotlib to place plots inline inside the notebook."
]
},
{
@@ -22,7 +22,7 @@
"%matplotlib inline\n",
"import yt\n",
"import numpy as np\n",
- "from matplotlib import pylab"
+ "import matplotlib.pyplot as plt"
]
},
{
@@ -91,13 +91,16 @@
},
"outputs": [],
"source": [
- "pylab.semilogy(times, rho_ex[:,0], '-xk', label='Minimum')\n",
- "pylab.semilogy(times, rho_ex[:,1], '-xr', label='Maximum')\n",
- "pylab.ylabel(\"Density ($g/cm^3$)\")\n",
- "pylab.xlabel(\"Time (Gyr)\")\n",
- "pylab.legend()\n",
- "pylab.ylim(1e-32, 1e-21)\n",
- "pylab.show()"
+ "fig, ax = plt.subplots()\n",
+ "ax.set(\n",
+ " xlabel=\"Time (Gyr)\",\n",
+ " ylabel=\"Density ($g/cm^3$)\",\n",
+ " yscale=\"log\",\n",
+ " ylim=(1e-32, 1e-21),\n",
+ ")\n",
+ "ax.plot(times, rho_ex[:,0], '-xk', label='Minimum')\n",
+ "ax.plot(times, rho_ex[:,1], '-xr', label='Maximum')\n",
+ "ax.legend()"
]
},
{
@@ -127,8 +130,9 @@
},
"outputs": [],
"source": [
+ "fig, ax = plt.subplots()\n",
"ray = ds.ray([0.1, 0.2, 0.3], [0.9, 0.8, 0.7])\n",
- "pylab.semilogy(np.array(ray[\"t\"]), np.array(ray[\"density\"]))"
+ "ax.semilogy(np.array(ray[\"t\"]), np.array(ray[\"density\"]))"
]
},
{
@@ -141,7 +145,7 @@
},
"outputs": [],
"source": [
- "print (ray[\"dts\"])"
+ "print(ray[\"dts\"])"
]
},
{
@@ -154,7 +158,7 @@
},
"outputs": [],
"source": [
- "print (ray[\"t\"])"
+ "print(ray[\"t\"])"
]
},
{
@@ -167,7 +171,7 @@
},
"outputs": [],
"source": [
- "print (ray[(\"gas\", \"x\")])"
+ "print(ray[\"gas\", \"x\"])"
]
},
{
@@ -192,10 +196,10 @@
"ds = yt.load_sample(\"IsolatedGalaxy\")\n",
"v, c = ds.find_max((\"gas\", \"density\"))\n",
"sl = ds.slice(2, c[0])\n",
- "print (sl[\"index\", \"x\"])\n",
- "print (sl[\"index\", \"z\"])\n",
- "print (sl[\"pdx\"])\n",
- "print (sl[\"gas\", \"density\"].shape)"
+ "print(sl[\"index\", \"x\"])\n",
+ "print(sl[\"index\", \"z\"])\n",
+ "print(sl[\"pdx\"])\n",
+ "print(sl[\"gas\", \"density\"].shape)"
]
},
{
@@ -216,7 +220,7 @@
"outputs": [],
"source": [
"frb = sl.to_frb((50.0, 'kpc'), 1024)\n",
- "print (frb[\"gas\", \"density\"].shape)"
+ "print(frb[\"gas\", \"density\"].shape)"
]
},
{
@@ -345,7 +349,7 @@
"outputs": [],
"source": [
"cg = ds.covering_grid(2, [0.0, 0.0, 0.0], ds.domain_dimensions * 2**2)\n",
- "print (cg[\"density\"].shape)"
+ "print(cg[\"density\"].shape)"
]
},
{
@@ -366,7 +370,7 @@
"outputs": [],
"source": [
"scg = ds.smoothed_covering_grid(2, [0.0, 0.0, 0.0], ds.domain_dimensions * 2**2)\n",
- "print (scg[\"density\"].shape)"
+ "print(scg[\"density\"].shape)"
]
},
{
@@ -379,9 +383,13 @@
],
"metadata": {
"kernelspec": {
- "display_name": "Python 3",
- "language": "python",
- "name": "python3"
+ "name": "python3",
+ "display_name": "Python 3.9.5 64-bit ('yt-dev': pyenv)",
+ "metadata": {
+ "interpreter": {
+ "hash": "14363bd97bed451d1329fb3e06aa057a9e955a9421c5343dd7530f5497723a41"
+ }
+ }
},
"language_info": {
"codemirror_mode": {
@@ -393,7 +401,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.8.8"
+ "version": "3.9.5"
}
},
"nbformat": 4,
diff --git a/doc/source/quickstart/5)_Derived_Fields_and_Profiles.ipynb b/doc/source/quickstart/5)_Derived_Fields_and_Profiles.ipynb
index ccc85383f49..d208b33caaa 100644
--- a/doc/source/quickstart/5)_Derived_Fields_and_Profiles.ipynb
+++ b/doc/source/quickstart/5)_Derived_Fields_and_Profiles.ipynb
@@ -21,10 +21,10 @@
"outputs": [],
"source": [
"%matplotlib inline\n",
- "import yt\n",
+ "import matplotlib.pyplot as plt\n",
"import numpy as np\n",
- "from yt import derived_field\n",
- "from matplotlib import pylab"
+ "import yt\n",
+ "from yt import derived_field"
]
},
{
@@ -49,7 +49,7 @@
"source": [
"@derived_field(name=\"dinosaurs\", units=\"K * cm/s\", sampling_type=\"cell\")\n",
"def _dinos(field, data):\n",
- " return data[(\"gas\", \"temperature\")] * data[(\"gas\", \"velocity_magnitude\")]"
+ " return data[\"gas\", \"temperature\"] * data[\"gas\", \"velocity_magnitude\"]"
]
},
{
@@ -72,7 +72,7 @@
"source": [
"ds = yt.load_sample(\"IsolatedGalaxy\")\n",
"dd = ds.all_data()\n",
- "print (list(dd.quantities.keys()))"
+ "print(list(dd.quantities.keys()))"
]
},
{
@@ -93,7 +93,7 @@
},
"outputs": [],
"source": [
- "print (dd.quantities.extrema((\"gas\", \"dinosaurs\")))"
+ "print(dd.quantities.extrema((\"gas\", \"dinosaurs\")))"
]
},
{
@@ -114,7 +114,7 @@
},
"outputs": [],
"source": [
- "print (dd.quantities.weighted_average_quantity((\"gas\", \"dinosaurs\"), weight=(\"gas\", \"temperature\")))"
+ "print(dd.quantities.weighted_average_quantity((\"gas\", \"dinosaurs\"), weight=(\"gas\", \"temperature\")))"
]
},
{
@@ -141,9 +141,9 @@
"bv = sp.quantities.bulk_velocity()\n",
"L = sp.quantities.angular_momentum_vector()\n",
"rho_min, rho_max = sp.quantities.extrema((\"gas\", \"density\"))\n",
- "print (bv)\n",
- "print (L)\n",
- "print (rho_min, rho_max)"
+ "print(bv)\n",
+ "print(L)\n",
+ "print(rho_min, rho_max)"
]
},
{
@@ -172,9 +172,13 @@
"source": [
"prof = yt.Profile1D(sp, (\"gas\", \"density\"), 32, rho_min, rho_max, True, weight_field=(\"gas\", \"mass\"))\n",
"prof.add_fields([(\"gas\", \"temperature\"), (\"gas\", \"dinosaurs\")])\n",
- "pylab.loglog(np.array(prof.x), np.array(prof[(\"gas\", \"temperature\")]), \"-x\")\n",
- "pylab.xlabel('Density $(g/cm^3)$')\n",
- "pylab.ylabel('Temperature $(K)$')"
+ "\n",
+ "fig, ax = plt.subplots()\n",
+ "ax.loglog(np.array(prof.x), np.array(prof[\"gas\", \"temperature\"]), \"-x\")\n",
+ "ax.set(\n",
+ " xlabel='Density $(g/cm^3)$',\n",
+ " ylabel='Temperature $(K)$',\n",
+ ")"
]
},
{
@@ -195,9 +199,12 @@
},
"outputs": [],
"source": [
- "pylab.loglog(np.array(prof.x), np.array(prof[(\"gas\", \"dinosaurs\")]), '-x')\n",
- "pylab.xlabel('Density $(g/cm^3)$')\n",
- "pylab.ylabel('Dinosaurs $(K cm / s)$')"
+ "fig, ax = plt.subplots()\n",
+ "ax.loglog(np.array(prof.x), np.array(prof[\"gas\", \"dinosaurs\"]), '-x')\n",
+ "ax.set(\n",
+ " xlabel='Density $(g/cm^3)$',\n",
+ " ylabel='Dinosaurs $(K cm / s)$',\n",
+ ")"
]
},
{
@@ -220,9 +227,13 @@
"source": [
"prof = yt.Profile1D(sp, (\"gas\", \"density\"), 32, rho_min, rho_max, True, weight_field=None)\n",
"prof.add_fields([(\"gas\", \"mass\")])\n",
- "pylab.loglog(np.array(prof.x), np.array(prof[(\"gas\", \"mass\")].in_units(\"Msun\")), '-x')\n",
- "pylab.xlabel('Density $(g/cm^3)$')\n",
- "pylab.ylabel('Cell mass $(M_\\odot)$')"
+ "\n",
+ "fig, ax = plt.subplots()\n",
+ "ax.loglog(np.array(prof.x), np.array(prof[\"gas\", \"mass\"].in_units(\"Msun\")), '-x')\n",
+ "ax.set(\n",
+ " xlabel='Density $(g/cm^3)$',\n",
+ " ylabel='Cell mass $(M_\\odot)$',\n",
+ ")"
]
},
{
@@ -278,9 +289,9 @@
"sp.set_field_parameter(\"bulk_velocity\", bv)\n",
"rv2 = sp.quantities.extrema((\"gas\", \"radial_velocity\"))\n",
"\n",
- "print (bv)\n",
- "print (rv1)\n",
- "print (rv2)"
+ "print(bv)\n",
+ "print(rv1)\n",
+ "print(rv2)"
]
}
],
diff --git a/doc/source/quickstart/index.rst b/doc/source/quickstart/index.rst
index d7a28f16970..b232f1028e9 100644
--- a/doc/source/quickstart/index.rst
+++ b/doc/source/quickstart/index.rst
@@ -16,7 +16,7 @@ To execute the quickstart interactively, you have a couple of options: 1) run
the notebook from your own system or 2) run it from the url
https://girder.hub.yt/#raft/5b5b4686323d12000122aa8a.
Option 1 requires an existing installation of yt (see
-:ref:`getting-and-installing-yt`), a copy of the yt source (which you may
+:ref:`installing-yt`), a copy of the yt source (which you may
already have depending on your installation choice), and a download of the
tutorial data-sets (total about 3 GB). If you know you are going to be a yt user
and have the time to download the data-sets, option 1 is a good choice. However,
diff --git a/doc/source/reference/api/api.rst b/doc/source/reference/api/api.rst
index 32bcfe64d73..e0f4a692ab8 100644
--- a/doc/source/reference/api/api.rst
+++ b/doc/source/reference/api/api.rst
@@ -58,6 +58,7 @@ Writing FITS images
~yt.visualization.fits_image.FITSProjection
~yt.visualization.fits_image.FITSOffAxisSlice
~yt.visualization.fits_image.FITSOffAxisProjection
+ ~yt.visualization.fits_image.FITSParticleProjection
Data Sources
------------
@@ -103,7 +104,7 @@ geometric.
~yt.data_objects.selection_objects.object_collection.YTDataCollection
~yt.data_objects.selection_objects.spheroids.YTSphere
~yt.data_objects.selection_objects.spheroids.YTEllipsoid
- ~yt.data_objects.selection_objects.cur_region.YTCutRegion
+ ~yt.data_objects.selection_objects.cut_region.YTCutRegion
~yt.data_objects.index_subobjects.grid_patch.AMRGridPatch
~yt.data_objects.index_subobjects.octree_subset.OctreeSubset
~yt.data_objects.index_subobjects.particle_container.ParticleContainer
@@ -157,27 +158,16 @@ These objects generate an "index" into multiresolution data.
Units
-----
-These classes and functions enable yt's symbolic unit handling system.
+yt's symbolic unit handling system is now based on the external library unyt. In
+complement, Dataset objects support the following methods to build arrays and
+scalars with physical dimensions.
.. autosummary::
yt.data_objects.static_output.Dataset.arr
yt.data_objects.static_output.Dataset.quan
- ~yt.units.unit_object.define_unit
- ~yt.units.unit_object.Unit
- ~yt.units.unit_registry.UnitRegistry
- ~yt.units.unit_systems.UnitSystem
- ~yt.units.yt_array.YTArray
- ~yt.units.yt_array.YTQuantity
- ~yt.units.yt_array.uconcatenate
- ~yt.units.yt_array.uintersect1d
- ~yt.units.yt_array.uunion1d
- ~yt.units.yt_array.unorm
- ~yt.units.yt_array.udot
- ~yt.units.yt_array.uvstack
- ~yt.units.yt_array.uhstack
- ~yt.units.yt_array.ustack
- ~yt.units.yt_array.display_ytarray
+
+
Frontends
---------
@@ -531,11 +521,11 @@ Field Functions
~yt.fields.field_info_container.FieldInfoContainer.add_field
~yt.data_objects.static_output.Dataset.add_field
- ~yt.data_objects.static_outputs.add_deposited_particle_field
- ~yt.data_objects.static_outputs.add_mesh_sampling_particle_field
- ~yt.data_objects.static_outputs.add_smoothed_particle_field
- ~yt.data_objects.static_outputs.add_gradient_fields
- ~yt.frontends.stream.data_structures.add_SPH_fields
+ ~yt.data_objects.static_output.Dataset.add_deposited_particle_field
+ ~yt.data_objects.static_output.Dataset.add_mesh_sampling_particle_field
+ ~yt.data_objects.static_output.Dataset.add_smoothed_particle_field
+ ~yt.data_objects.static_output.Dataset.add_gradient_fields
+ ~yt.frontends.stream.data_structures.StreamParticlesDataset.add_sph_fields
Particle Filters
----------------
@@ -797,7 +787,7 @@ Miscellaneous Types
.. autosummary::
- ~yt.config.YTConfigParser
+ ~yt.config.YTConfig
~yt.utilities.parameter_file_storage.ParameterFileStore
~yt.utilities.parallel_tools.parallel_analysis_interface.ObjectIterator
~yt.utilities.parallel_tools.parallel_analysis_interface.ParallelAnalysisInterface
@@ -819,7 +809,6 @@ Cosmology Calculator
~yt.utilities.cosmology.Cosmology.angular_scale
~yt.utilities.cosmology.Cosmology.luminosity_distance
~yt.utilities.cosmology.Cosmology.lookback_time
- ~yt.utilities.cosmology.Cosmology.hubble_time
~yt.utilities.cosmology.Cosmology.critical_density
~yt.utilities.cosmology.Cosmology.hubble_parameter
~yt.utilities.cosmology.Cosmology.expansion_factor
@@ -858,8 +847,6 @@ These are for the pytest infrastructure:
.. autosummary::
- ~conftest.tempdir
- ~conftest.answer_file
~conftest.hashing
~yt.utilities.answer_testing.answer_tests.grid_hierarchy
~yt.utilities.answer_testing.answer_tests.parentage_relationships
@@ -867,8 +854,6 @@ These are for the pytest infrastructure:
~yt.utilities.answer_testing.answer_tests.projection_values
~yt.utilities.answer_testing.answer_tests.field_values
~yt.utilities.answer_testing.answer_tests.pixelized_projection_values
- ~yt.utilities.answer_testing.answer_tests.simulated_halo_mass_function
- ~yt.utilities.answer_testing.answer_tests.analytic_halo_mass_function
~yt.utilities.answer_testing.answer_tests.small_patch_amr
~yt.utilities.answer_testing.answer_tests.big_patch_amr
~yt.utilities.answer_testing.answer_tests.generic_array
@@ -878,6 +863,5 @@ These are for the pytest infrastructure:
~yt.utilities.answer_testing.answer_tests.phase_plot_attribute
~yt.utilities.answer_testing.answer_tests.generic_image
~yt.utilities.answer_testing.answer_tests.axial_pixelization
- ~yt.utilities.answer_testing.answer_tests.light_cone_projection
~yt.utilities.answer_testing.answer_tests.extract_connected_sets
~yt.utilities.answer_testing.answer_tests.VR_image_comparison
diff --git a/doc/source/reference/changelog.rst b/doc/source/reference/changelog.rst
index 73a00467703..f31b5943681 100644
--- a/doc/source/reference/changelog.rst
+++ b/doc/source/reference/changelog.rst
@@ -12,6 +12,250 @@ The `CREDITS file `_
contains the most up-to-date list of everyone who has contributed to the yt
source code.
+yt 4.0
+------
+
+Welcome to yt 4.0! This release is the result of several years worth of
+developer effort and has been in progress since the mid 3.x series. Please keep
+in mind that this release **will** have breaking changes. Please see the yt 4.0
+differences page for how you can expect behavior to differ from the 3.x series.
+
+This is a manually curated list of pull requests that went in to yt 4.0,
+representing a subset of `the full
+list `__.
+
+New Functions
+^^^^^^^^^^^^^
+
+- ``yt.load_sample`` (PR
+ #\ `2417 `__, PR
+ #\ `2496 `__, PR
+ #\ `2875 `__, PR
+ #\ `2877 `__, PR
+ #\ `2894 `__, PR
+ #\ `3262 `__, PR
+ #\ `3263 `__, PR
+ #\ `3277 `__, PR
+ #\ `3309 `__, and PR
+ #\ `3336 `__)
+- ``yt.set_log_level`` (PR
+ #\ `2869 `__ and PR
+ #\ `3094 `__)
+- ``list_annotations`` method for plots (PR
+ #\ `2562 `__)
+
+API improvements
+^^^^^^^^^^^^^^^^
+
+- ``yt.load`` with support for ``os.PathLike`` objects, improved UX
+ and moved a new ``yt.loaders`` module, along with sibling functions (PR
+ #\ `2405 `__, PR
+ #\ `2722 `__, PR
+ #\ `2695 `__, PR
+ #\ `2818 `__, and PR
+ #\ `2831 `__, PR
+ #\ `2832 `__)
+- ``Dataset`` now has a more useful repr (PR
+ #\ `3217 `__)
+- Explicit JPEG export support (PR
+ #\ `2549 `__)
+- ``annotate_clear`` is now ``clear_annotations`` (PR
+ #\ `2569 `__)
+- Throw an error if field access is ambiguous (PR
+ #\ `2967 `__)
+
+Newly supported data formats
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Arepo
+~~~~~
+
+- PR #\ `1807 `__
+- PR #\ `2236 `__
+- PR #\ `2244 `__
+- PR #\ `2344 `__
+- PR #\ `2434 `__
+- PR #\ `3258 `__
+- PR #\ `3265 `__
+- PR #\ `3291 `__
+
+Swift
+~~~~~
+
+- PR #\ `1962 `__
+
+Improved support and frontend specific bugfixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+adaptahop
+~~~~~~~~~
+
+- PR #\ `2678 `__
+
+AMRVAC
+~~~~~~
+
+- PR #\ `2541 `__
+- PR #\ `2745 `__
+- PR #\ `2746 `__
+- PR #\ `3215 `__
+
+ART
+~~~
+
+- PR #\ `2688 `__
+
+ARTIO
+~~~~~
+
+- PR #\ `2613 `__
+
+Athena++
+~~~~~~~~
+
+- PR #\ `2985 `__
+
+Boxlib
+~~~~~~
+
+- PR #\ `2807 `__
+- PR #\ `2814 `__
+- PR #\ `2938 `__ (AMReX)
+
+Enzo-E (formerly Enzo-P)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- PR #\ `3273 `__
+- PR #\ `3274 `__
+- PR #\ `3290 `__
+- PR #\ `3372 `__
+
+fits
+~~~~
+
+- PR #\ `2246 `__
+- PR #\ `2345 `__
+
+Gadget
+~~~~~~
+
+- PR #\ `2145 `__
+- PR #\ `3233 `__
+- PR #\ `3258 `__
+
+Gadget FOF Halo
+~~~~~~~~~~~~~~~
+
+- PR #\ `2296 `__
+
+GAMER
+~~~~~
+
+- PR #\ `3033 `__
+
+Gizmo
+~~~~~
+
+- PR #\ `3234 `__
+
+MOAB
+~~~~
+
+- PR #\ `2856 `__
+
+Owls
+~~~~
+
+- PR #\ `3325 `__
+
+Ramses
+~~~~~~
+
+- PR #\ `2679 `__
+- PR #\ `2714 `__
+- PR #\ `2960 `__
+- PR #\ `3017 `__
+- PR #\ `3018 `__
+
+Tipsy
+~~~~~
+
+- PR #\ `2193 `__
+
+Octree Frontends
+~~~~~~~~~~~~~~~~
+
+- Ghost zone access (PR
+ #\ `2425 `__ and PR
+ #\ `2958 `__)
+- Volume Rendering (PR
+ #\ `2610 `__)
+
+Configuration file
+^^^^^^^^^^^^^^^^^^
+
+- Config files are now in `TOML `__ (PR
+ #\ `2981 `__)
+- Allow a local plugin file (PR
+ #\ `2534 `__)
+- Allow per-field local config (PR
+ #\ `1931 `__)
+
+yt CLI
+^^^^^^
+
+- Fix broken command-line options (PR
+ #\ `3361 `__)
+- Drop yt hub command (PR
+ #\ `3363 `__)
+
+Deprecations
+^^^^^^^^^^^^
+
+- Smoothed fields are no longer necessary (PR
+ #\ `2194 `__)
+- Energy and momentum field names are more accurate (PR
+ #\ `3059 `__)
+- Incorrectly-named ``WeightedVariance`` is now
+ ``WeightedStandardDeviation`` and the old name has been deprecated
+ (PR #\ `3132 `__)
+- Colormap auto-registration has been changed and yt 4.1 will not
+ register ``cmocean`` (PR
+ #\ `3175 `__ and PR
+ #\ `3214 `__)
+
+Removals
+~~~~~~~~
+
+- ``analysis_modules`` has been
+ `extracted `__ (PR
+ #\ `2081 `__)
+- Interactive volume rendering has been
+ `extracted `__ (PR
+ #\ `2896 `__)
+- The bundled version of ``poster`` has been removed (PR
+ #\ `2783 `__)
+- The deprecated ``particle_position_relative`` field has been removed
+ (PR #\ `2901 `__)
+- Deprecated functions have been removed (PR
+ #\ `3007 `__)
+- Vendored packages have been removed (PR
+ #\ `3008 `__)
+- ``yt.pmods`` has been removed (PR
+ #\ `3061 `__)
+- yt now utilizes unyt as an external package (PR
+ #\ `2219 `__, PR
+ #\ `2300 `__, and PR
+ #\ `2303 `__)
+
+Version 3.6.1
+-------------
+
+Version 3.6.1 is a bugfix release. It includes the following backport:
+
+- hotfix: support matplotlib 3.3.0.
+ See `PR 2754 `__.
+
Version 3.6.0
-------------
@@ -39,33 +283,35 @@ Major Changes and New Features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- New frontend support for the code AMRVAC. Many thanks to Clement Robert
- and Niels Claes who were major contributors to this initiative. Relevant PRs include:
- - Initial PR to support AMRVAC native data files
- `PR 2321 `__.
- - added support for dust fields and derived fields
- `PR 2387 `__.
- - added support for derived fields for hydro runs
- `PR 2381 `__.
- - API documentation and docstrings for AMRVAC frontend
- `PR 2384 `__,
- `PR 2380 `__,
- `PR 2382 `__.
- - testing-related PRs for AMRVAC:
- `PR 2379 `__,
- `PR 2360 `__.
- - add verbosity to logging of geometry or `geometry_override`
- `PR 2421 `__.
- - add attribute to `_code_unit_attributes` specific to AMRVAC to ensure
- consistent renormalisation of AMRVAC datasets. See
- `PR 2357 `__.
- - parse AMRVAC's parfiles if user-provided
- `PR 2369 `__.
- - ensure that min_level reflects dataset that has refinement
- `PR 2475 `__.
- - fix derived unit parsing `PR 2362 `__.
- - update energy field to be `energy_density` and have units of code
- pressure `PR 2376 `__.
+- New frontend support for the code AMRVAC. Many thanks to Clément Robert
+ and Niels Claes who were major contributors to this initiative. Relevant PRs include
+
+ - Initial PR to support AMRVAC native data files
+ `PR 2321 `__.
+ - added support for dust fields and derived fields
+ `PR 2387 `__.
+ - added support for derived fields for hydro runs
+ `PR 2381 `__.
+ - API documentation and docstrings for AMRVAC frontend
+ `PR 2384 `__,
+ `PR 2380 `__,
+ `PR 2382 `__.
+ - testing-related PRs for AMRVAC:
+ `PR 2379 `__,
+ `PR 2360 `__.
+ - add verbosity to logging of geometry or ``geometry_override``
+ `PR 2421 `__.
+ - add attribute to ``_code_unit_attributes`` specific to AMRVAC to ensure
+ consistent renormalisation of AMRVAC datasets. See
+ `PR 2357 `__.
+ - parse AMRVAC's parfiles if user-provided
+ `PR 2369 `__.
+ - ensure that min_level reflects dataset that has refinement
+ `PR 2475 `__.
+ - fix derived unit parsing `PR 2362 `__.
+ - update energy field to be ``energy_density`` and have units of code
+ pressure `PR 2376 `__.
+
- Support for the AdaptaHOP halo finder code
`PR 2385 `__.
- yt now supports geographic transforms and projections of data with
@@ -363,8 +609,8 @@ Other Infrastructure
- Added a welcomebot to our github page for new contributors, see
`PR 2181 `__.
- Added a pep8 bot to pre-run before tests, see
- `PR 2179 `__
- `PR 2184 `__,
+ `PR 2184 `__ and
`PR 2185 `__.
Version 3.5.0
@@ -493,8 +739,8 @@ Additional Improvements
will be registered for a dataset if the dependent particle filter is
registered with a dataset. See `PR 1624
`__.
-- The ``save()`` method of the various yt plot objets now optionally can accept
- a tuple of strings instead of a string. If a tuple is supplied, the elments
+- The ``save()`` method of the various yt plot objects now optionally can accept
+ a tuple of strings instead of a string. If a tuple is supplied, the elements
are joined with ``os.sep`` to form a path. See `PR 1630
`__.
- The quiver callback now accepts a ``plot_args`` keyword argument that allows
@@ -544,7 +790,7 @@ Additional Improvements
1914 `__.
- ``ParticleProjectionPlot`` now supports the ``annotate_particles`` plot
callback. See `PR 1765 `__.
-- Optmized the performance of off-axis projections for octree AMR data. See `PR
+- Optimized the performance of off-axis projections for octree AMR data. See `PR
1766 `__.
- Added support for several radiative transfer fields in the ARTIO frontend. See
`PR 1804 `__.
@@ -1147,7 +1393,7 @@ Major enhancements
:ref:`GAMER `, and :ref:`Gizmo ` data
formats.
* The unit system associated with a dataset is now customizable, defaulting to
- CGS. See :ref:`unit_systems`.
+ CGS.
* Enhancements and usability improvements for analysis modules, especially the
``absorption_spectrum``, ``photon_simulator``, and ``light_ray`` modules. See
:ref:`synthetic-observations`.
diff --git a/doc/source/reference/code_support.rst b/doc/source/reference/code_support.rst
index d200e83a385..4f320cd32ce 100644
--- a/doc/source/reference/code_support.rst
+++ b/doc/source/reference/code_support.rst
@@ -12,66 +12,78 @@ as inputs. Below is a list showing what level of support is provided for
each code. See :ref:`loading-data` for examples of loading a dataset from
each supported output format using yt.
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Capability ► | Fluid | Particles | Parameters | Units | Read on | Load Raw | Part of | Level of |
-| Code/Format ▼ | Quantities | | | | Demand | Data | test suite | Support |
-+=======================+============+===========+============+=======+==========+==========+============+==========+
-| AMRVAC | Y | N | Y | Y | Y | Y | Y | Partial |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| ART | Y | Y | Y | Y | Y [#f2]_ | Y | N | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| ARTIO | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Athena | Y | N | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Castro | Y | Y [#f3]_ | Partial | Y | Y | Y | N | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Chombo | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Enzo | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| FITS | Y | N/A | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| FLASH | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Gadget | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| GAMER | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Gasoline | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Gizmo | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Grid Data Format (GDF)| Y | N/A | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Maestro | Y [#f1]_ | N | Y | Y | Y | Y | N | Partial |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| MOAB | Y | N/A | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Nyx | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| openPMD | Y | Y | N | Y | Y | Y | N | Partial |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Orion | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| OWLS/EAGLE | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Piernik | Y | N/A | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Pluto | Y | N | Y | Y | Y | Y | Y | Partial |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| RAMSES | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| Tipsy | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
-| WarpX | Y | Y | Y | Y | Y | Y | Y | Full |
-+-----------------------+------------+-----------+------------+-------+----------+----------+------------+----------+
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Capability ► | Fluid | Particles | Parameters | Units | Read on | Load Raw | Part of | Level of |
+| Code/Format ▼ | Quantities | | | | Demand | Data | test suite | Support |
++=======================+============+===========+============+=======+==========+==========+============+=============+
+| AMRVAC | Y | N | Y | Y | Y | Y | Y | Partial |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| AREPO | Y | Y | Y | Y | Y | Y | Y | Full [#f4]_ |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| ART | Y | Y | Y | Y | Y [#f2]_ | Y | N | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| ARTIO | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Athena | Y | N | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Athena++ | Y | N | Y | Y | Y | Y | Y | Partial |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Castro | Y | Y [#f3]_ | Partial | Y | Y | Y | N | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Chombo | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Enzo | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Enzo-E | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Exodus II | ? | ? | ? | ? | ? | ? | ? | ? |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| FITS | Y | N/A | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| FLASH | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Gadget | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| GAMER | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Gasoline | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Gizmo | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Grid Data Format (GDF)| Y | N/A | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| IAMR | ? | ? | ? | ? | ? | ? | ? | ? |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Maestro | Y [#f1]_ | N | Y | Y | Y | Y | N | Partial |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| MOAB | Y | N/A | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Nyx | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| openPMD | Y | Y | N | Y | Y | Y | N | Partial |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Orion | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| OWLS/EAGLE | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Piernik | Y | N/A | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Pluto | Y | N | Y | Y | Y | Y | Y | Partial |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| RAMSES | Y | Y | Y | Y | Y [#f2]_ | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Tipsy | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| WarpX | Y | Y | Y | Y | Y | Y | Y | Full |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
.. [#f1] one-dimensional base-state not read in currently.
.. [#f2] These handle mesh fields using an in-memory octree that has not been parallelized.
Datasets larger than approximately 1024^3 will not scale well.
.. [#f3] Newer versions of Castro that use BoxLib's standard particle format are supported.
- The older ASCII format is not.
+ The older ASCII format is not.
+.. [#f4] The Voronoi cells are currently treated as SPH-like particles, with a smoothing
+ length proportional to the cube root of the cell volume.
If you have a dataset that uses an output format not yet supported by yt, you
can either input your data following :ref:`loading-numpy-array` or
diff --git a/doc/source/reference/command-line.rst b/doc/source/reference/command-line.rst
index 54a6d9e61cd..27cf466f790 100644
--- a/doc/source/reference/command-line.rst
+++ b/doc/source/reference/command-line.rst
@@ -8,6 +8,10 @@ Command-Line Usage
Interactive Prompt
~~~~~~~~~~~~~~~~~~
+.. warning::
+
+ This section describes a script targeted for removal in yt 4.2.0
+
The interactive prompt offers a number of excellent opportunities for
exploration of data. While there are challenges for repeatability, and some
operations will be more challenging to operate in parallel, interactive prompts
@@ -35,8 +39,8 @@ or
yt load DD0030/DD0030
This will spawn ``iyt``, but the dataset given on the command line will
-already be in the namespace as ``ds``. With interactive mode, you can use the
-``pylab`` module to interactively plot.
+already be in the namespace as ``ds``. With interactive mode, you can use
+``matplotlib.pyplot`` to build plots interactively.
Command-line Functions
~~~~~~~~~~~~~~~~~~~~~~
@@ -45,7 +49,7 @@ The :code:`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
+an IPython notebook session, and more. To get a quick list of what is
available, just type:
.. code-block:: bash
@@ -82,21 +86,21 @@ 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
+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
+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
+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:
.. code-block:: bash
$ yt plot DD0010/moving7_0010
-Well, that looks pretty bad! What has happened here is that the center of the
+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.
+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:
@@ -104,10 +108,10 @@ becomes a column density:
$ yt plot -p DD0010/moving7_0010
-Now that looks much better! Note that all three axes' projections appear
+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
+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:
.. code-block:: bash
@@ -131,43 +135,27 @@ help
Help lists all of the various command-line options in yt.
-
-bugreport
-+++++++++
-
-Encountering a bug in your own code can be a big hassle, but it can be
-exponentially worse to find it in someone else's. That's why we tried to
-make it as easy as possible for users to report bugs they find in yt.
-After you go through the necessary channels to make sure you're not just
-making a mistake (see :ref:`asking-for-help`), you can submit bug
-reports using this nice utility.
-
instinfo and version
++++++++++++++++++++
This gives information about where your yt installation is, what version
and changeset you're using and more.
-load
-++++
-
-This will start the iyt interactive environment with your specified
-dataset already loaded. See :ref:`interactive-prompt` for more details.
mapserver
+++++++++
-Ever wanted to interact with your data using the
-`google maps `_ interface? Now you can by using the
-yt mapserver. See :ref:`mapserver` for more details.
+Ever wanted to interact with your data using a
+`google maps `_-style interface? Now you can by using the
+yt mapserver. See :ref:`mapserver` 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
+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;
.. code-block:: bash
@@ -205,28 +193,18 @@ By specifying the axis, center, width, etc. (run ``yt help plot`` for
details), you can create slices and projections easily at the
command-line.
-upload_notebook
-+++++++++++++++
-
-This command will accept the filename of a ``.ipynb`` file (generated from an
-IPython notebook session) and upload it to the `yt hub
-`__ where others will be able to view it, and
-download it. This is an easy method for recording a sequence of commands,
-their output, narrative information, and then sharing that with others. These
-notebooks will be viewable online, and the appropriate URLs will be returned on
-the command line.
-
rpdb
++++
-Connect to a currently running (on localhost) rpd session.
+Connect to a currently running (on localhost) rpdb session. See
+:ref:`remote-debugging` for more info.
notebook
++++++++
-Launches an IPython 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 an IPython notebook using CPUs on a remote
+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
@@ -234,14 +212,34 @@ 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, the resolution, and the maximum density in a variety of units.
-It is tantamount to performing the ``print_stats()`` inside of yt.
+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:
+
+.. code-block:: bash
+
+ yt stats GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0150 --max --min
+
+or a different field can be specified using the ``-f`` flag:
+
+.. code-block:: bash
+
+ 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:
+
+.. code-block:: bash
+
+ 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``
+your repository (e.g. stable, 2.0, development, etc.). Adding the ``--all``
flag will update the dependencies as well.
.. _upload-image:
@@ -265,38 +263,6 @@ 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 `_.
-Hub helper
-~~~~~~~~~~
-
-The :code:`yt hub` command-line tool allows to interact with the `yt hub
-`__. The following subcommands are currently available:
-
-.. config_help:: yt hub
-
-register
-++++++++
-
-This subcommand starts an interactive process of creating an account on the `yt
-hub `__. Please note that the yt Hub also supports multiple OAuth
-providers such as Google, Bitbucket and GitHub for authentication.
-See :ref:`hub-APIkey` for more information.
-
-start
-+++++
-
-This subcommand launches the Jupyter Notebook on the `yt Hub `__
-with a chosen Hub folder mounted to the ``/data`` directory inside the notebook.
-If no path is given all the `example yt datasets
-`_ are mounted by default. The appropriate URL
-allowing to access the Notebook will be returned on the commandline.
-
-Example:
-
-.. code-block:: bash
-
- $ yt hub start
- $ yt hub start /user/xarthisius/Public
-
download
~~~~~~~~
diff --git a/doc/source/reference/configuration.rst b/doc/source/reference/configuration.rst
index 0f6aa2f6fb4..1a95abe64ca 100644
--- a/doc/source/reference/configuration.rst
+++ b/doc/source/reference/configuration.rst
@@ -14,7 +14,9 @@ The Configuration
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 :ref:`globally` or :ref:`locally`.
+The configuration can either be stored :ref:`globally ` or :ref:`locally `.
+
+.. _global-conf:
Global Configuration
^^^^^^^^^^^^^^^^^^^^
@@ -45,6 +47,8 @@ options from the configuration file, e.g.:
$ yt config rm yt maximum_stored_datasets
+.. _local-conf:
+
Local Configuration
^^^^^^^^^^^^^^^^^^^
@@ -98,10 +102,10 @@ 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.
-.. _global-config:
+.. _config-options:
-Available Global Configuration Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Available Configuration Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following external parameters are available. A number of parameters are
used internally.
@@ -152,7 +156,7 @@ It is possible to customize the default behaviour of plots using per-field confi
The default options for plotting a given field can be specified in the configuration file
in ``[plot.field_type.field_name]`` blocks. The available keys are
-* ``cmap`` (default: ``yt.default_colormap``, see :ref:`global-config`): the colormap to
+* ``cmap`` (default: ``yt.default_colormap``, see :ref:`config-options`): the colormap to
use for the field.
* ``log`` (default: ``True``): use a log scale (or symlog if ``linthresh`` is also set).
* ``linthresh`` (default: ``None``): if set to a float different than ``None`` and ``log`` is
@@ -203,9 +207,8 @@ by defining ``plugin_filename`` in your ``yt.toml`` file, as mentioned above.
.. note::
You can tell that your system plugin file is being parsed by watching for a logging
- message when you import yt. Note that both the ``yt load`` and ``iyt``
- command line entry points parse the plugin file, so the ``my_plugins.py``
- file will be parsed if you enter yt that way.
+ message when you import yt. Note that the ``yt load`` command line entry point parses
+ the plugin file.
Local project plugin file
@@ -221,7 +224,7 @@ 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 I created a plugin file containing:
+For example, if one created a plugin file containing:
.. code-block:: python
@@ -285,8 +288,8 @@ Adding Custom Colormaps
To add custom :ref:`colormaps` to your plugin file, you must use the
:func:`~yt.visualization.color_maps.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 :ref:`custom-colormaps`. Remember that you don't need
+colormap of your choice and then add it to the plugin file. You can see
+an example of this in :ref:`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
``yt``.
diff --git a/doc/source/reference/demeshening.rst b/doc/source/reference/demeshening.rst
index 9a6ab30c89e..cb1aaf848ae 100644
--- a/doc/source/reference/demeshening.rst
+++ b/doc/source/reference/demeshening.rst
@@ -7,9 +7,9 @@ With yt-4.0, the method by which particles are indexed changed considerably.
Whereas in previous versions, particles were indexed based on their position in
an octree (the structure of which was determined by particle number density),
in yt-4.0 this system was overhauled to utilize a `bitmap
-index`_ based on a space-filling
+index `_ based on a space-filling
curve, using a `enhanced word-aligned
-hybrid` boolean array as their
+hybrid `_ boolean array as their
backend.
.. note::
@@ -21,7 +21,7 @@ backend.
By avoiding the use of octrees as a base mesh, yt is able to create *much* more
accurate SPH visualizations. We have a `gallery demonstrating
-this`_ but even in this
+this `_ but even in this
side-by-side comparison the differences can be seen quite easily, with the left
image being from the old, octree-based approach and the right image the new,
meshless approach.
@@ -39,10 +39,8 @@ load only those particles it needs.
.. note::
The theory and implementation of yt's bitmap indexing system is described in
- some detail in the `yt 4.0
- paper`_ in the section entitled
- `Indexing Discrete-Point
- Datasets`_.
+ some detail in the `yt 4.0 paper `_
+ in the section entitled `Indexing Discrete-Point Datasets `_.
In brief, however, what this relies on is two numbers, ``index_order1`` and
``index_order2``. These control the "coarse" and "refined" sets of indices,
@@ -146,7 +144,7 @@ be read from disk before expensive selection operations are conducted.
For those situations that involve particles with regions of influence -- such
as smoothed particle hydrodynamics, where particles have associated smoothing
-lenghts -- these are taken into account when conducting the indexing system.
+lengths -- these are taken into account when conducting the indexing system.
Efficiency of Index Orders
--------------------------
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 20b4b725d37..999f0e2be80 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -13,7 +13,9 @@ code.
code_support
command-line
api/api
+ api/modules
configuration
python_introduction
field_list
+ demeshening
changelog
diff --git a/doc/source/reference/python_introduction.rst b/doc/source/reference/python_introduction.rst
index b12db3ea86b..38e1826c88e 100644
--- a/doc/source/reference/python_introduction.rst
+++ b/doc/source/reference/python_introduction.rst
@@ -50,22 +50,16 @@ signs. Let's inaugurate the occasion appropriately -- type this::
As you can see, this printed out the string "Hello, world." just as we
expected. Now let's try a more advanced string, one with a number in it. For
-this we'll use the percent (``%``) operator, which is the manner by which
-values are fed into a formatted string. We'll print pi, but only with three
-digits of accuracy.::
+this we'll use an "f-string", which is the preferred way to format strings in modern Python.
+We'll print pi, but only with three digits of accuracy.::
- >>> print("Pi is precisely %0.2f" % (3.1415926))
+ >>> print(f"Pi is precisely {3.1415926:0.2f}")
This took the number we fed it (3.1415926) and printed it out as a floating
-point number with two decimal places. Now let's try something a bit different
+point number with two decimal places. Now let's try something a bit different
-- let's print out both the name of the number and its value.::
- >>> print("%s is precisely %0.2f" % ("pi", 3.1415926))
-
-As you can see, we used ``%s`` to say that the string should print a value as a
-string (the supplied value does not have to be a string -- ``"pi"`` could be
-replaced with, for instance, another number!) and then supplied the string to
-print, as well.
+ >>> print(f"{'pi'} is precisely {3.1415926:0.2f}")
And there you have it -- the very basics of starting up Python, and some very
simple mechanisms for printing values out. Now let's explore a few types of
@@ -128,9 +122,6 @@ This works for floating points as well. Now we can do math on these numbers::
>>> print(a + 5.1)
>>> print(a / 2.0)
-Because of a historical aversion to floating point division in Python (which is
-now changing) it's always safest to ensure that either the numerator or the
-denominator is a floating point number.
Now that we have a couple primitive datatypes, we can move on to sequences --
lists and tuples. These two objects are very similar, in that they are
@@ -643,7 +634,7 @@ covers mechanisms for combining arrays of different shapes and sizes, which can
be tricky but also extremely powerful. We won't discuss the idea of
broadcasting here, simply because I don't know that I could do it justice! The
NumPy Docs have a great `section on broadcasting
-`_.
+`_.
Scripted Usage
++++++++++++++
@@ -736,8 +727,8 @@ perspective and interactively.
Python and Related References
+++++++++++++++++++++++++++++
* `Python quickstart `_
- * `Learn Python the Hard Way `_
+ * `Learn Python the Hard Way `_
* `Byte of Python `_
- * `Dive Into Python `_
- * `Numpy docs `_
+ * `Dive Into Python `_
+ * `Numpy docs `_
* `Matplotlib docs `_
diff --git a/doc/source/sharing_data.rst b/doc/source/sharing_data.rst
deleted file mode 100644
index 05d300549df..00000000000
--- a/doc/source/sharing_data.rst
+++ /dev/null
@@ -1,117 +0,0 @@
-.. _sharing-data:
-
-The yt Hub
-==========
-
-.. contents::
- :depth: 2
- :local:
- :backlinks: none
-
-What is the yt Hub?
--------------------
-
-The yt data Hub is a mechanism by which images, data objects and projects can be
-shared with other people. For instance, one can upload a dataset and allow other
-people to remotely analyze it with a jupyter notebook or upload notebooks and
-view them from any web browser.
-
-.. note:: All items posted on the hub are public!
-
-Over time, more widgets will be added, and more datatypes will be able to be
-uploaded. If you are interested in adding more ways of sharing data, please
-email the developers' list. We would like to add support for 3D widgets such
-as isocontours as well as interactive binning and rebinning of data from yt
-data objects, to be displayed as phase plots and profiles.
-
-.. note:: Working with the Hub requires additional dependencies to be installed.
- You can obtain them by running: ``pip install yt[hub]``.
-
-.. _hub-APIkey:
-
-Obtaining an API key
---------------------
-
-In order to interact with the yt Hub, you need to obtain API key, which is
-available only for authenticated users. You can `log into
-`_ the Hub using your Google, GitHub or
-Bitbucket account. After you log in, an API key can be generated under the *My
-account* page, which can be accessed through the dropdown menu in the upper
-right corner.
-
-.. image:: _static/apiKey01.jpg
- :width: 50 %
-
-Select the *API keys* tab and press *Create new key* button:
-
-.. image:: _static/apiKey02.jpg
- :width: 50 %
-
-By convention, the *Name* field of API keys can be used to specify what
-application is making use of the key in a human-readable way e.g. ``yt
-command``, although you may name your key however you want.
-
-.. image:: _static/apiKey03.jpg
- :width: 50 %
-
-After the API Key is created you can obtain it by clicking *show* link:
-
-.. image:: _static/apiKey04.jpg
- :width: 50 %
-
-For more information about API keys please see `this document
-`__.
-
-After you have gotten your API key, update your config file:
-
-.. code-block:: none
-
- $ yt config set yt hub_api_key 3fd1de56c2114c13a2de4dd51g10974b
-
-Replace ``3fd1de56c2114c13a2de4dd51g10974b`` with your API key.
-
-Registering a User
-^^^^^^^^^^^^^^^^^^
-
-If you do not wish to use OAuth authentication, you can create a Hub account
-using ``yt`` command. To register a user:
-
-.. code-block:: bash
-
- $ yt hub register
-
-This will walk you through the process of registering. You will need to supply
-a name, a username, a password and an email address. Apart from creating a new
-user account, it will also generate an API key and append it to the yt's config
-file. At this point, you're ready to go!
-
-What Can Be Uploaded
---------------------
-
-Currently, the yt hub can accept these types of data:
-
- * Raw data files, scripts.
- * IPython notebooks: these are stored on the hub and are made available for
- download and via the IPython `nbviewer `_
- service.
-
-How to Upload Data
-------------------
-
-Uploading data can be performed using the ``girder-cli`` command tool or
-directly via the web interface. Please refer to ``girder-cli`` `documentation page
-`_ for additional
-information.
-
-Uploading Notebooks
-^^^^^^^^^^^^^^^^^^^
-
-Notebooks can be uploaded from the bash command line:
-
-.. code-block:: bash
-
- yt upload_notebook notebook_file.ipynb
-
-After the notebook is finished uploading, yt will print a link to the raw
-notebook as well as an nbviewer link to the same notebook. Your notebooks will
-be stored under your hub Public directory.
diff --git a/doc/source/visualizing/Volume_Rendering_Tutorial.ipynb b/doc/source/visualizing/Volume_Rendering_Tutorial.ipynb
index 62766865fea..12ab3e9a24b 100644
--- a/doc/source/visualizing/Volume_Rendering_Tutorial.ipynb
+++ b/doc/source/visualizing/Volume_Rendering_Tutorial.ipynb
@@ -178,7 +178,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "For the change to the camera to take affect, we have to explictly render again: "
+ "For the change to the camera to take affect, we have to explicitly render again: "
]
},
{
diff --git a/doc/source/visualizing/callbacks.rst b/doc/source/visualizing/callbacks.rst
index 76601767ac8..ec5898cafbb 100644
--- a/doc/source/visualizing/callbacks.rst
+++ b/doc/source/visualizing/callbacks.rst
@@ -22,7 +22,7 @@ of available callbacks. For example:
.. code-block:: python
- slc = SlicePlot(ds, 0, "density")
+ slc = SlicePlot(ds, "x", ("gas", "density"))
slc.annotate_title("This is a Density plot")
would add the :func:`~yt.visualization.plot_modifications.TitleCallback` to
@@ -30,7 +30,7 @@ the plot object. All of the callbacks listed below are available via
similar ``annotate_`` functions.
To clear one or more annotations from an existing plot, see the
-:ref:`clear_annotations() function `.
+:ref:`clear_annotations function `.
For a brief demonstration of a few of these callbacks in action together,
see the cookbook recipe: :ref:`annotations-recipe`.
@@ -62,7 +62,7 @@ of the x-plane (i.e. with axes in the y and z directions):
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- s = yt.SlicePlot(ds, "x", "density")
+ s = yt.SlicePlot(ds, "x", ("gas", "density"))
s.set_axes_unit("kpc")
# Plot marker and text in data coords
@@ -97,7 +97,7 @@ dataset from AMRVAC :
import yt
ds = yt.load("amrvac/bw_polar_2D0000.dat")
- s = yt.plot_2d(ds, "density")
+ s = yt.plot_2d(ds, ("gas", "density"))
s.set_background_color("density", "black")
# Plot marker and text in data coords
@@ -136,12 +136,15 @@ Clear Callbacks (Some or All)
to the plot. Note that the index goes from 0..N, and you can
specify the index of the last added annotation as -1.
+ (This is a proxy for
+ :func:`~yt.visualization.plot_window.clear_annotations`.)
+
.. python-script::
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_scale()
p.annotate_timestamp()
@@ -158,15 +161,18 @@ List Currently Applied Callbacks
This function will print a list of each of the currently applied
callbacks together with their index. The index can be used with
- :ref:`clear_annotations() function ` to remove a
+ :ref:`clear_annotations() function ` to remove a
specific callback.
+ (This is a proxy for
+ :func:`~yt.visualization.plot_window.list_annotations`.)
+
.. python-script::
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_scale()
p.annotate_timestamp()
p.list_annotations()
@@ -191,7 +197,7 @@ Overplot Arrow
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- slc = yt.SlicePlot(ds, "z", "density", width=(10, "kpc"), center="c")
+ slc = yt.SlicePlot(ds, "z", ("gas", "density"), width=(10, "kpc"), center="c")
slc.annotate_arrow((0.5, 0.5, 0.5), length=0.06, plot_args={"color": "blue"})
slc.save()
@@ -218,16 +224,16 @@ Clump Finder Callback
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
data_source = ds.disk([0.5, 0.5, 0.5], [0.0, 0.0, 1.0], (8.0, "kpc"), (1.0, "kpc"))
- c_min = 10 ** np.floor(np.log10(data_source["density"]).min())
- c_max = 10 ** np.floor(np.log10(data_source["density"]).max() + 1)
+ c_min = 10 ** np.floor(np.log10(data_source[("gas", "density")]).min())
+ c_max = 10 ** np.floor(np.log10(data_source[("gas", "density")]).max() + 1)
- master_clump = Clump(data_source, "density")
+ master_clump = Clump(data_source, ("gas", "density"))
master_clump.add_validator("min_cells", 20)
find_clumps(master_clump, c_min, c_max, 2.0)
leaf_clumps = master_clump.leaves
- prj = yt.ProjectionPlot(ds, 2, "density", center="c", width=(20, "kpc"))
+ prj = yt.ProjectionPlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
prj.annotate_clumps(leaf_clumps)
prj.save("clumps")
@@ -253,8 +259,8 @@ Overplot Contours
import yt
ds = yt.load("Enzo_64/DD0043/data0043")
- s = yt.SlicePlot(ds, "x", "density", center="max")
- s.annotate_contour("temperature")
+ s = yt.SlicePlot(ds, "x", ("gas", "density"), center="max")
+ s.annotate_contour(("gas", "temperature"))
s.save()
.. _annotate-quivers:
@@ -288,12 +294,13 @@ Axis-Aligned Data Sources
p = yt.ProjectionPlot(
ds,
"z",
- "density",
+ ("gas", "density"),
center=[0.5, 0.5, 0.5],
weight_field="density",
width=(20, "kpc"),
)
- p.annotate_quiver("velocity_x", "velocity_y", factor=16, plot_args={"color": "purple"})
+ p.annotate_quiver(("gas", "velocity_x"), ("gas", "velocity_y"), factor=16,
+ plot_args={"color": "purple"})
p.save()
Off-Axis Data Sources
@@ -319,10 +326,10 @@ Off-Axis Data Sources
import yt
ds = yt.load("Enzo_64/DD0043/data0043")
- s = yt.OffAxisSlicePlot(ds, [1, 1, 0], ["density"], center="c")
+ s = yt.OffAxisSlicePlot(ds, [1, 1, 0], [("gas", "density")], center="c")
s.annotate_cquiver(
- "cutting_plane_velocity_x",
- "cutting_plane_velocity_y",
+ ("gas", "cutting_plane_velocity_x"),
+ ("gas", "cutting_plane_velocity_y"),
factor=10,
plot_args={"color": "orange"},
)
@@ -353,7 +360,7 @@ Overplot Grids
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- slc = yt.SlicePlot(ds, "z", "density", width=(10, "kpc"), center="max")
+ slc = yt.SlicePlot(ds, "z", ("gas", "density"), width=(10, "kpc"), center="max")
slc.annotate_grids()
slc.save()
@@ -379,7 +386,7 @@ Overplot Cell Edges
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- slc = yt.SlicePlot(ds, "z", "density", width=(10, "kpc"), center="max")
+ slc = yt.SlicePlot(ds, "z", ("gas", "density"), width=(10, "kpc"), center="max")
slc.annotate_cell_edges()
slc.save()
@@ -434,7 +441,7 @@ Overplot Halo Annotations
data_ds = yt.load("Enzo_64/RD0006/RedshiftOutput0006")
halos_ds = yt.load("rockstar_halos/halos_0.0.bin")
- prj = yt.ProjectionPlot(data_ds, "z", "density")
+ prj = yt.ProjectionPlot(data_ds, "z", ("gas", "density"))
prj.annotate_halos(halos_ds, annotate_field="particle_identifier")
prj.save()
@@ -457,7 +464,7 @@ Overplot a Straight Line
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.ProjectionPlot(ds, "z", "density", center="m", width=(10, "kpc"))
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"), center="m", width=(10, "kpc"))
p.annotate_line((0.3, 0.4), (0.8, 0.9), coord_system="axis")
p.save()
@@ -493,7 +500,7 @@ Overplot Magnetic Field Quivers
"mass_unit": (1e17, "Msun"),
},
)
- p = yt.ProjectionPlot(ds, "z", "density", center="c", width=(300, "kpc"))
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"), center="c", width=(300, "kpc"))
p.annotate_magnetic_field(plot_args={"headlength": 3})
p.save()
@@ -515,7 +522,7 @@ Annotate a Point With a Marker
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- s = yt.SlicePlot(ds, "z", "density", center="c", width=(10, "kpc"))
+ s = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(10, "kpc"))
s.annotate_marker((-2, -2), coord_system="plot", plot_args={"color": "blue", "s": 500})
s.save()
@@ -544,7 +551,7 @@ Overplotting Particle Positions
import yt
ds = yt.load("Enzo_64/DD0043/data0043")
- p = yt.ProjectionPlot(ds, "x", "density", center="m", width=(10, "Mpc"))
+ p = yt.ProjectionPlot(ds, "x", ("gas", "density"), center="m", width=(10, "Mpc"))
p.annotate_particles((10, "Mpc"))
p.save()
@@ -555,7 +562,7 @@ To plot only the central particles
import yt
ds = yt.load("Enzo_64/DD0043/data0043")
- p = yt.ProjectionPlot(ds, "x", "density", center="m", width=(10, "Mpc"))
+ p = yt.ProjectionPlot(ds, "x", ("gas", "density"), center="m", width=(10, "Mpc"))
sp = ds.sphere([0.5, 0.5, 0.5], ds.quan(1, "Mpc"))
p.annotate_particles((10, "Mpc"), data_source=sp)
p.save()
@@ -578,7 +585,7 @@ Overplot a Circle on a Plot
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.ProjectionPlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_sphere([0.5, 0.5, 0.5], radius=(2, "kpc"), circle_args={"color": "black"})
p.save()
@@ -606,8 +613,8 @@ Overplot Streamlines
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- s = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
- s.annotate_streamlines("velocity_x", "velocity_y")
+ s = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
+ s.annotate_streamlines(("gas", "velocity_x"), ("gas", "velocity_y"))
s.save()
.. _annotate-line-integral-convolution:
@@ -636,8 +643,8 @@ Overplot Line Integral Convolution
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- s = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
- s.annotate_line_integral_convolution("velocity_x", "velocity_y", lim=(0.5, 0.65))
+ s = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
+ s.annotate_line_integral_convolution(("gas", "velocity_x"), ("gas", "velocity_y"), lim=(0.5, 0.65))
s.save()
.. _annotate-text:
@@ -660,7 +667,7 @@ Overplot Text
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- s = yt.SlicePlot(ds, "z", "density", center="max", width=(10, "kpc"))
+ s = yt.SlicePlot(ds, "z", ("gas", "density"), center="max", width=(10, "kpc"))
s.annotate_text((2, 2), "Galaxy!", coord_system="plot")
s.save()
@@ -681,7 +688,7 @@ Add a Title
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.ProjectionPlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_title("Density Plot")
p.save()
@@ -709,7 +716,7 @@ Overplot Quivers for the Velocity Field
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.SlicePlot(ds, "z", "density", center="m", width=(10, "kpc"))
+ p = yt.SlicePlot(ds, "z", ("gas", "density"), center="m", width=(10, "kpc"))
p.annotate_velocity(plot_args={"headwidth": 4})
p.save()
@@ -742,7 +749,7 @@ Add the Current Time and/or Redshift
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_timestamp()
p.save()
@@ -752,7 +759,7 @@ Add a Physical Scale Bar
~~~~~~~~~~~~~~~~~~~~~~~~
.. function:: annotate_scale(corner='lower_right', coeff=None, \
- unit=None, pos=None,
+ unit=None, pos=None, \
scale_text_format="{scale} {units}", \
max_frac=0.16, min_frac=0.015, \
coord_system='axis', text_args=None, \
@@ -781,7 +788,7 @@ Add a Physical Scale Bar
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.SlicePlot(ds, "z", "density", center="c", width=(20, "kpc"))
+ p = yt.SlicePlot(ds, "z", ("gas", "density"), center="c", width=(20, "kpc"))
p.annotate_scale()
p.save()
@@ -808,10 +815,10 @@ Annotate Triangle Facets Callback
import yt
# Load data file
- pf = yt.load("MoabTest/fng_usrbin22.h5m")
+ ds = yt.load("MoabTest/fng_usrbin22.h5m")
# Create the desired slice plot
- s = yt.SlicePlot(pf, "z", ("moab", "TALLY_TAG"))
+ s = yt.SlicePlot(ds, "z", ("moab", "TALLY_TAG"))
# get triangle vertices from file (in this case hdf5)
@@ -847,7 +854,7 @@ Annotate Mesh Lines Callback
import yt
ds = yt.load("MOOSE_sample_data/out.e")
- sl = yt.SlicePlot(ds, 2, ("connect1", "nodal_aux"))
+ sl = yt.SlicePlot(ds, "z", ("connect1", "nodal_aux"))
sl.annotate_mesh_lines(plot_args={"color": "black"})
sl.save()
@@ -863,9 +870,9 @@ Overplot the Path of a Ray
Adds a line representing the projected path of a ray across the plot. The
ray can be either a
- :class:`~yt.data_objects.selection_data_containers.YTOrthoRay`,
- :class:`~yt.data_objects.selection_data_containers.YTRay`, or a
- :class:`~trident.light_ray.LightRay`
+ :class:`~yt.data_objects.selection_objects.ray.YTOrthoRay`,
+ :class:`~yt.data_objects.selection_objects.ray.YTRay`, or a
+ Trident :class:`~trident.light_ray.LightRay`
object. annotate_ray() will properly account for periodic rays across the
volume.
@@ -876,7 +883,7 @@ Overplot the Path of a Ray
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
oray = ds.ortho_ray(0, (0.3, 0.4))
ray = ds.ray((0.1, 0.2, 0.3), (0.6, 0.7, 0.8))
- p = yt.ProjectionPlot(ds, "z", "density")
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"))
p.annotate_ray(oray)
p.annotate_ray(ray)
p.save()
diff --git a/doc/source/visualizing/colormaps/index.rst b/doc/source/visualizing/colormaps/index.rst
index f08cfcba265..e4366ef946e 100644
--- a/doc/source/visualizing/colormaps/index.rst
+++ b/doc/source/visualizing/colormaps/index.rst
@@ -115,7 +115,7 @@ available in a local window:
yt.show_colormaps()
-or to output just a few colormaps to an image file, try:
+or to output the original yt colormaps to an image file, try:
.. code-block:: python
@@ -144,12 +144,12 @@ callback:
.. code-block:: python
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- p = yt.ProjectionPlot(ds, "z", "density")
+ p = yt.ProjectionPlot(ds, "z", ("gas", "density"))
- p.set_cmap(field="density", cmap="jet")
+ p.set_cmap(field=("gas", "density"), cmap="turbo")
p.save("proj_with_jet_cmap.png")
- p.set_cmap(field="density", cmap="hot")
+ p.set_cmap(field=("gas", "density"), cmap="hot")
p.save("proj_with_hot_cmap.png")
For more information about the callbacks available to Plot Window objects,
diff --git a/doc/source/visualizing/geographic_projections_and_transforms.rst b/doc/source/visualizing/geographic_projections_and_transforms.rst
index fc4caa76b23..14ca5c3e010 100644
--- a/doc/source/visualizing/geographic_projections_and_transforms.rst
+++ b/doc/source/visualizing/geographic_projections_and_transforms.rst
@@ -49,9 +49,9 @@ would execute the following commands:
.. code-block:: bash
- brew install proj geos
- brew upgrade proj geos
- pip install --no-binary :all: shapely cartopy
+ $ brew install proj geos
+ $ brew upgrade proj geos
+ $ python -m pip install --no-binary :all: shapely cartopy
On ubuntu you'll need to install the following packages: ``libproj-dev``,
diff --git a/doc/source/visualizing/interactive_data_visualization.rst b/doc/source/visualizing/interactive_data_visualization.rst
index d04facc4473..1de537d1c9b 100644
--- a/doc/source/visualizing/interactive_data_visualization.rst
+++ b/doc/source/visualizing/interactive_data_visualization.rst
@@ -3,94 +3,10 @@
Interactive Data Visualization
==============================
-In version 3.3 of yt, an experimental, hardware-accelerated interactive volume
-renderer was introduced. This interactive renderer is based on OpenGL and
-natively understands adaptive mesh refinement data; this enables
-(GPU) memory-efficient loading of data. The data is copied from CPU memory
-onto the GPU as a series of 3D textures, which are then rendered to an
-interactive window. The window itself is the view from a conceptual "camera",
-which can be rotated, zoomed, and so on. The color of each displayed pixel is
-computed by a "fragment shader" which is executed on each grid that is
-displayed. The fragment shaders currently implemented in yt enable computing
-(and then mapping to a colormap) the maximum value along each pixel's line of
-sight and an unweighted integration of values along each pixel's line of sight
-(and subsequent mapping to a colormap.) An experimental transfer function
-shader has been implemented, but is not yet functioning correctly. For more
-information, see :ref:`projection-types`.
+The interactive, OpenGL-based volume rendering system for yt has been exported
+into its own package, called ``yt_idv``.
-A comprehensive description of the OpenGL volume rendering is beyond the scope
-of this document. However, a more detailed explanation can be found in `this
-guide `_.
-
-Much of the Interactive Data Visualization (IDV) interface is designed to
-mimic the interface available for software volume rendering (see
-:ref:`volume_rendering`) so that in future versions API compatibility may lead
-to greater code reuse both for scripts that create visualizations and for
-internal visualization objects.
-
-Installation
-^^^^^^^^^^^^
-
-In order to use Interactive Data Visualization (IDV) you need to install
-`PyOpenGL `_ and `cyglfw3
-`_ along with their respective
-dependencies, e.g. `glfw3 `_ is required to be installed
-before you can ``pip install cyglfw3``. Please carefully read installation
-instructions provided on pypi pages of both packages.
-
-Using the interactive renderer
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can simply pass dataset to :meth:`~yt.interactive_render`. By default
-it will load all data and render gas density:
-
-.. code-block:: python
-
- import yt
-
- ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- yt.interactive_render(ds)
-
-Alternatively you can provide a data object as a first argument to
-:meth:`~yt.interactive_render` if your dataset is too big to fit GPU memory:
-
-.. code-block:: python
-
- import yt
-
- ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- sp = ds.sphere("max", (0.1, "Mpc"))
-
- cam_pos = ds.arr([0.1, 0.1, 0.1], "Mpc").in_units("code_length")
- yt.interactive_render(
- sp, field="pressure", cam_position=cam_pos, window_size=(512, 512)
- )
-
-A successful call to :meth:`~yt.interactive_render` should create a new window
-called *vol_render*.
-
-.. image:: _images/idv.jpg
- :width: 1000
-
-By default it renders a Maximum Intensity Projection of the density field (see
-:ref:`projection-types` for more information). The rendering can be
-dynamically modified using the following keybindings:
-
-1
- Switch to MIP fragment shader
-2
- Switch to integration fragment shader
-L
- Switch between linear and logarithmic scales
-W
- Zoom in the camera
-S
- Zoom out the camera
-C
- Change the colormap
-
-Pressing the *h* key will print all the available key bindings in a terminal window.
-The camera can be moved around by holding a left mouse button while moving the mouse.
-
-More advanced initialization of interactive volume renderer can be found in
-:ref:`cookbook-opengl_vr`.
+Documentation, including installation instructions, can be found at `its
+website `_, and the source code is
+hosted under the yt-project organization on github at `yt_idv
+`_.
diff --git a/doc/source/visualizing/manual_plotting.rst b/doc/source/visualizing/manual_plotting.rst
index d702bd17959..56dd140c053 100644
--- a/doc/source/visualizing/manual_plotting.rst
+++ b/doc/source/visualizing/manual_plotting.rst
@@ -44,14 +44,14 @@ of any data two-dimensional data object:
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- c = ds.find_max("density")[1]
- proj = ds.proj("density", 0)
+ _, c = ds.find_max(("gas", "density"))
+ proj = ds.proj(("gas", "density"), 0)
width = (10, "kpc") # we want a 1.5 mpc view
res = [1000, 1000] # create an image with 1000x1000 pixels
frb = proj.to_frb(width, res, center=c)
- plt.imshow(np.array(frb["density"]))
+ plt.imshow(np.array(frb["gas", "density"]))
plt.savefig("my_perfect_figure.png")
Note that in the above example the axes tick marks indicate pixel indices. If you
@@ -93,7 +93,7 @@ using them matters.
frb = slc.to_frb((20, "kpc"), 512)
frb.apply_gauss_beam(nbeam=30, sigma=2.0)
frb.apply_white_noise(5e-23)
- plt.imshow(frb["density"].d)
+ plt.imshow(frb["gas", "density"].d)
plt.savefig("frb_filters.png")
Currently available filters:
@@ -130,7 +130,7 @@ This is perhaps the simplest thing to do. yt provides a number of one
dimensional objects, and these return a 1-D numpy array of their contents with
direct dictionary access. As a simple example, take a
:class:`~yt.data_objects.selection_data_containers.YTOrthoRay` object, which can be
-created from a index by calling ``pf.ortho_ray(axis, center)``.
+created from a index by calling ``ds.ortho_ray(axis, center)``.
.. python-script::
@@ -143,7 +143,7 @@ created from a index by calling ``pf.ortho_ray(axis, center)``.
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
- c = ds.find_max("density")[1]
+ _, c = ds.find_max(("gas", "density"))
ax = 0 # take a line cut along the x axis
# cutting through the y0,z0 such that we hit the max density
@@ -151,13 +151,13 @@ created from a index by calling ``pf.ortho_ray(axis, center)``.
# Sort the ray values by 'x' so there are no discontinuities
# in the line plot
- srt = np.argsort(ray["x"])
+ srt = np.argsort(ray["index", "x"])
plt.subplot(211)
- plt.semilogy(np.array(ray["x"][srt]), np.array(ray["density"][srt]))
+ plt.semilogy(np.array(ray["index", "x"][srt]), np.array(ray["gas", "density"][srt]))
plt.ylabel("density")
plt.subplot(212)
- plt.semilogy(np.array(ray["x"][srt]), np.array(ray["temperature"][srt]))
+ plt.semilogy(np.array(ray["index", "x"][srt]), np.array(ray["gas", "temperature"][srt]))
plt.xlabel("x")
plt.ylabel("temperature")
diff --git a/doc/source/visualizing/mapserver.rst b/doc/source/visualizing/mapserver.rst
index d0eeb50066f..a175c38d028 100644
--- a/doc/source/visualizing/mapserver.rst
+++ b/doc/source/visualizing/mapserver.rst
@@ -3,13 +3,19 @@
Mapserver - A Google-Maps-like Interface to your Data
-----------------------------------------------------
-The mapserver is a new, experimental feature. It's based on `Leaflet
+The mapserver is an experimental feature. It's based on `Leaflet
|
+
-yt is an open-source, permissively-licensed python package for analyzing and
+yt is an open-source, permissively-licensed Python library for analyzing and
visualizing volumetric data.
yt supports structured, variable-resolution meshes, unstructured meshes, and
@@ -50,54 +52,11 @@ conda install -c conda-forge yt
or with pip:
```shell
-pip install yt
+python -m pip install yt
```
-To get set up with a development version, you want to clone this repository:
-
-```shell
-git clone https://github.com/yt-project/yt yt-git
-cd yt-git
-```
-
-and work within a conda environment:
-
-```shell
-# Create a conda environment named yt-git
-$ conda create -n yt-git python=3.6
-# Activate it
-$ source activate yt-git
-# Make sure you run the latest version of conda
-$ conda update conda
-# Install yt's runtime dependencies
-$ conda install -c conda-forge yt --only-deps
-# Install yt's build dependencies
-$ conda install -c conda-forge cython
-# Make sure you run the latest version of pip
-$ pip install --upgrade pip
-$ pip install -v -e .
-# Output installed packages
-$ conda env export
-```
-
-Alternatively, you can install yt in a
-[virtualenv](https://packaging.python.org/installing/#creating-virtual-environments):
-
-```shell
-# It is conventional to create virtualenvs at ~/.virtualenv/
-$ mkdir -p ~/.virtualenv
-# Assuming your version of Python 3 meets the minimal requirement
-# create a virtualenv named yt-git
-$ python3 -m venv ~/.virtualenv/yt-git
-# Activate it
-$ source ~/.virtualenv/yt-git/bin/activate
-# Make sure you run the latest version of pip
-$ pip install --upgrade pip
-# Assuming you have cd'd into yt-git
-$ pip install -e .
-# Output installed packages
-$ pip freeze
-```
+More information on the various ways to install yt, and in particular to install from source,
+can be found on [the project's website](https://yt-project.org/docs/dev/installing.html).
## Getting Started
diff --git a/conftest.py b/conftest.py
index 29edf369e9f..ccdb5390739 100644
--- a/conftest.py
+++ b/conftest.py
@@ -1,6 +1,7 @@
import os
import shutil
import tempfile
+from importlib.util import find_spec
from pathlib import Path
import pytest
@@ -71,6 +72,91 @@ def pytest_configure(config):
config.addinivalue_line(
"markers", "big_data: Run answer tests that require large data files."
)
+ for value in (
+ # treat most warnings as errors
+ "error",
+ # >>> internal deprecation warnings with no obvious solution
+ # see https://github.com/yt-project/yt/issues/3381
+ (
+ r"ignore:The requested field name 'pd?[xyz]' is ambiguous and corresponds "
+ "to any one of the following field types.*:yt._maintenance.deprecation.VisibleDeprecationWarning"
+ ),
+ # >>> warnings emitted by testing frameworks, or in testing contexts
+ # we still have some yield-based tests, awaiting for transition into pytest
+ "ignore::pytest.PytestCollectionWarning",
+ # imp is used in nosetest
+ "ignore:the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses:DeprecationWarning",
+ # the deprecation warning message for imp changed in Python 3.10, so we ignore both versions
+ "ignore:the imp module is deprecated in favour of importlib and slated for removal in Python 3.12; see the module's documentation for alternative uses:DeprecationWarning",
+ # matplotlib warnings related to the Agg backend which is used in CI, not much we can do about it
+ "ignore:Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.:UserWarning",
+ "ignore:tight_layout . falling back to Agg renderer:UserWarning",
+ #
+ # >>> warnings from wrong values passed to numpy
+ # these should normally be curated out of the test suite but they are too numerous
+ # to deal with in a reasonable time at the moment.
+ "ignore:invalid value encountered in log10:RuntimeWarning",
+ "ignore:divide by zero encountered in log10:RuntimeWarning",
+ "ignore:invalid value encountered in true_divide:RuntimeWarning",
+ #
+ # >>> there are many places in yt (most notably at the frontend level)
+ # where we open files but never explicitly close them
+ # Although this is in general bad practice, it can be intentional and
+ # justified in contexts where reading speeds should be optimized.
+ # It is not clear at the time of writing how to approach this,
+ # so I'm going to ignore this class of warnings altogether for now.
+ "ignore:unclosed file.*:ResourceWarning",
+ ):
+ config.addinivalue_line("filterwarnings", value)
+
+ # at the time of writing, astropy's wheels are behind numpy's latest
+ # version but this doesn't cause actual problems in our test suite, so
+ # we allow this warning to pass.
+ # last checked with astropy 4.2.1
+ config.addinivalue_line(
+ "filterwarnings",
+ (
+ "ignore:numpy.ndarray size changed, may indicate binary incompatibility. "
+ "Expected 80 from C header, got 88 from PyObject:RuntimeWarning"
+ ),
+ )
+ if find_spec("astropy") is not None:
+ # astropy triggers this warning from itself, there's not much we can do on our side
+ # last checked with astropy 4.2.1
+ config.addinivalue_line(
+ "filterwarnings", "ignore::astropy.wcs.wcs.FITSFixedWarning"
+ )
+
+ if find_spec("cartopy") is not None:
+ # cartopy still triggers this numpy warning
+ # last checked with cartopy 0.19.0
+ config.addinivalue_line(
+ "filterwarnings",
+ (
+ "ignore:`np.float` is a deprecated alias for the builtin `float`. "
+ "To silence this warning, use `float` by itself. "
+ "Doing this will not modify any behavior and is safe. "
+ "If you specifically wanted the numpy scalar type, use `np.float64` here."
+ ":DeprecationWarning: "
+ ),
+ )
+ # this warning *still* shows up on cartopy 0.19 so we'll ignore it
+ config.addinivalue_line(
+ "filterwarnings",
+ (
+ r"ignore:The default value for the \*approx\* keyword argument to "
+ r"\w+ will change from True to False after 0\.18\.:UserWarning"
+ ),
+ )
+ # this one could be resolved by upgrading PROJ on Jenkins,
+ # but there's isn't much else that can be done about it.
+ config.addinivalue_line(
+ "filterwarnings",
+ (
+ "ignore:The Stereographic projection in Proj older than 5.0.0 incorrectly "
+ "transforms points when central_latitude=0. Use this projection with caution.:UserWarning"
+ ),
+ )
def pytest_collection_modifyitems(config, items):
diff --git a/doc/cheatsheet.tex b/doc/cheatsheet.tex
index 0a8e852c221..b3a2065e1bd 100644
--- a/doc/cheatsheet.tex
+++ b/doc/cheatsheet.tex
@@ -116,7 +116,6 @@ \subsection{Command Line yt}
{\bf {-}{-}help} (e.g. {\bf yt render {-}{-}help}) for detailed help for that command
including a list of the available flags.
-\texttt{iyt}\textemdash\ Load yt and IPython. \\
\texttt{yt load} \textit{dataset} \textemdash\ Load a single dataset. \\
\texttt{yt help} \textemdash\ Print yt help information. \\
\texttt{yt stats} \textit{dataset} \textemdash\ Print stats of a dataset. \\
@@ -182,7 +181,7 @@ \subsection{YTArray}
\subsection{IPython Tips}
\settowidth{\MyLen}{\texttt{multicol} }
These tips work if IPython has been loaded, typically either by invoking
-\texttt{iyt} or \texttt{yt load} on the command line, or using the IPython notebook (\texttt{yt notebook}).
+\texttt{yt load} on the command line, or using the IPython notebook (\texttt{yt notebook}).
\texttt{Tab complete} \textemdash\ IPython will attempt to auto-complete a
variable or function name when the \texttt{Tab} key is pressed, e.g. \textit{HaloFi}\textendash\texttt{Tab} would auto-complete
to \textit{HaloFinder}. This also works with imports, e.g. \textit{from numpy.random.}\textendash\texttt{Tab}
diff --git a/doc/source/about/index.rst b/doc/source/about/index.rst
index 650e10b3ae3..859acd1f991 100644
--- a/doc/source/about/index.rst
+++ b/doc/source/about/index.rst
@@ -30,28 +30,22 @@ to the project. For a list of those members and a description of their
contributions to the code, see
`our members website.