Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Removes blocking behavior when trident is not configured #142

Open
wants to merge 25 commits into
base: main
Choose a base branch
from
Open

Removes blocking behavior when trident is not configured #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
faa031f
Updating front page of docs.
chummels Jun 24, 2020
0ed785c
Changing install docs.
chummels Jun 24, 2020
d76daf0
Rewriting parse_config to prevent it from expecting user input.
chummels Jun 24, 2020
018e9e2
Removing special behavior for READTHEDOCS since code will no longer b…
chummels Jun 24, 2020
d51d4bd
Changing create_conf to configure
chummels Jun 24, 2020
a395687
Parsing config only when necessary for function to run for ion_balance.
chummels Jun 24, 2020
bf6c619
Parsing config only when necessary for function to run for ray_genera…
chummels Jun 24, 2020
68a8a63
Parsing config only when necessary for function to run for spectrum_g…
chummels Jun 24, 2020
fa4dff3
Removing check_import() because evidently the astropy bug that made t…
chummels Jun 24, 2020
6beb171
Making parse_config give verbose error when first time checked.
chummels Jun 24, 2020
6b1512f
Changing subsequent errors to use mylog.
chummels Jun 24, 2020
5b20325
Changing configure to be auto_config function.
chummels Jun 24, 2020
e257928
Adding trident exceptions
chummels Jun 24, 2020
0fb29bf
Using exceptions instead of mylog for errors.
chummels Jun 24, 2020
b5906ca
Removing ionization_table kwarg from ray_generation because not actua…
chummels Jun 24, 2020
b274247
Removing unused import
chummels Jun 24, 2020
cb239df
Updating use of exceptions
chummels Jun 24, 2020
da7d699
Removing excess whitespace for flake
chummels Jun 24, 2020
df49d60
Merge branch 'master' into install
chummels Jun 26, 2020
e0170cc
Adding some more text during auto_config.
chummels Jun 26, 2020
b7db7aa
Adding text to auto_config.
chummels Jun 26, 2020
47b5365
Fixing test failure.
chummels Jun 26, 2020
faaa977
Updating installation docs to address PR comments. Removing demesh refs.
chummels Jul 10, 2020
ca58836
Updating install instructions to address new auto_config()
chummels Jul 10, 2020
95d3365
deprecating keyword.
chummels Jul 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions doc/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
Trident Documentation
=====================

Trident is a Python package for creating synthetic absorption-line spectra
from astrophysical hydrodynamics simulations. It utilizes the yt package
to read in simulation datasets and extends it to provide realistic
synthetic observations appropriate for studies of the interstellar,
circumgalactic, and intergalactic media.
Trident is a Python package for calculating ion populations and creating
synthetic absorption-line spectra from astrophysical hydrodynamics simulations.
It utilizes the yt package to read in simulation datasets and extends it to
provide realistic synthetic observations appropriate for studies of the
interstellar, circumgalactic, and intergalactic media.

To avoid confusion, make sure you are viewing the correct documentation for
the version of Trident you are using:
Expand Down
137 changes: 66 additions & 71 deletions doc/source/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,48 +10,42 @@ Follow these steps to successfully install Trident and its dependencies.
Versions of Trident
-------------------

Previously, there were three versions of Trident: the `stable version
<http://trident.readthedocs.io/en/stable>`_, the `developent version
<http://trident.readthedocs.io/en/latest>`_, and the `demeshening version
There are two versions of Trident: the `stable version
<http://trident.readthedocs.io/en/stable>`_, and the `developent version
<http://trident.readthedocs.io/en/latest>`_. The stable version is tried and
tested, and it operates on the most recent stable version of yt. The
development version is actively being updated with new features, and it is
also tied to the development version of yt, so occasionally unforseen bugs
can crop up as these new features are added.

If you are dealing with an SPH or Voronoi Tesselation code like Gadget, Gizmo,
AREPO, Gasoline, or Changa, you will get best and fastest results from using the
development versions of Trident and yt, since there have been a number of
updates to these codes to better treat particle data natively (previously
referred to as the demeshening. For more details about the demeshening, see
`this notebook
<https://nbviewer.jupyter.org/url/trident-project.org/notebooks/trident_demesh_install.ipynb>`_.
The stable version is tried and tested, and it normally operates on a stable
version of yt. The development version is actively being updated with new
features, and it is also tied to the development version of yt, so occasionally
unforseen bugs can crop up as these new features are added. The demeshening
version is currently in beta and active development and is used for better
results on particle-based datasets.

After Trident 1.2 was released on September 19, 2019, the demeshening version
was merged with the main development branch. Now, there are only the stable
version and the development version.

The installation steps are slightly different between the two versions,
so pay attention in the steps below. Don't worry if you want to change later,
you can always switch between the two versions easily enough by following the
directions in :ref:`uninstallation`.

.. note::
The demeshening (development) version treats particle-based
datasets more natively. The demeshening version will give faster and more
accurate results with less memory overhead for particle-based datasets.
For more information about the demeshening version, please see our
`demeshening notebook
<https://nbviewer.jupyter.org/url/trident-project.org/notebooks/trident_demesh_install.ipynb>`_. **Note, the installation instructions in the notebook should be ignored.**
Instead, follow the instructions for :ref:`install-dev`.

The installation steps are slightly different between the two versions, in that
the stable version of Trident requires a stable release of yt, whereas
the development version of Trident requires the development version of yt, both
built from source. Don't worry if you want to change later, you can always
switch between the two versions easily enough by following the directions in
:ref:`uninstallation`.

.. _step-1:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since yt is a hard dependency for trident, it should be possible to just to pip install trident to get stable releases of both codes. It might be useful to add a suggestion to try that before installing yt and trident separately.


Step 1: Install yt
Step 1: Install yt
------------------

`yt <http://yt-project.org>`_ is a python-based software package for the
analysis and visualization of a variety of different datasets, including
`yt <http://yt-project.org>`_ is a python-based software package for the
analysis and visualization of a variety of different datasets, including
astrophysical hydrodynamical data. yt is a dependency of Trident, so you
must install it before Trident will work. There are several methods for
installing yt, which are all discussed in detail in the `yt installation
documentation <http://yt-project.org/doc/installing.html>`_.
must install it before Trident will work. There are several methods for
installing yt, which are all discussed in detail in the `yt installation
documentation <http://yt-project.org/doc/installing.html>`_.

We find that the easiest way to install yt is with the all-in-one install
We find that the easiest way to install yt is with the all-in-one install
script, which installs yt and its dependencies via a new conda installation::

$ wget https://raw.githubusercontent.com/yt-project/yt/master/doc/install_script.sh
Expand All @@ -61,7 +55,7 @@ script, which installs yt and its dependencies via a new conda installation::
$ ... update your path flag as described by the install_script.sh

Alternatively, if you already have conda installed, you can skip the commands
above and just run the following command to get yt and its dependencies.
above and just run the following command to get yt and its dependencies.
To get the nightly build of the development version of yt, type::

$ conda install -c http://use.yt/with_conda/ -c conda-forge yt
Expand All @@ -84,9 +78,9 @@ You can install the most recent stable release of Trident using pip::
Installing the Development Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To get the development version, you'll pull the source code from its
repository using git, which should be installed as part of your yt
installation. If it isn't try: ``conda install git``. After that, you'll
To get the development version, you'll pull the source code from its
repository using git, which should be installed as part of your yt
installation. If it isn't try: ``conda install git``. After that, you'll
use pip to install the source directly. The development version of Trident
requires the yt-4.0 development version of yt as well. Go to your desired
source code installation directory and run::
Expand All @@ -106,39 +100,40 @@ source code installation directory and run::
Step 3: Get Ionization Table and Verify Installation
----------------------------------------------------

In order to calculate the ionization fractions for various ions from
density, temperature, metallicity fields, you will need an ionization table
In order to calculate the ionization fractions for various ions from
density, temperature, metallicity fields, you will need an ionization table
datafile and a configuration file. Because this datafile can be large, it is
not packaged with the main source code. The first time you try to do anything
that requires it, Trident will attempt to automatically set this all up for
you with a series of interactive prompts. **This step requires an internet
connection the first time you run it.**
not packaged with the main source code. The first time that you import
Trident, you will be prompted to download these files through a series of
interactive prompts. **This step requires an internet connection the first
time you run it.** To initiate this directly, run the ``trident.auto_config()``.

In addition, Trident provides a simple test function to verify that your
In addition, Trident provides a simple test function to verify that your
install is functioning correctly. This function not only tries to set up
your configuration and download your ion table file, but it will
create a simple one-zone dataset, generate a ray through it, and
create a spectrum from that ray. This should execute very quickly,
and if it succeeds it demonstrates that your installation has been totally
your configuration and download your ion table file, but it will
create a simple one-zone dataset, generate a ray through it, and
create a spectrum from that ray. This should execute very quickly,
and if it succeeds it demonstrates that your installation has been totally
successful::

$ python
>>> import trident
>>> trident.verify()
>>> trident.auto_config()
...Series of Interactive Prompts...
>>> trident.verify()

If you cannot directly access the internet on this computer, or you lack write
access to your ``$HOME`` directory, or this step fails for any reason, please
access to your ``$HOME`` directory, or this step fails for any reason, please
follow our documentation on :ref:`manual-config`.

.. _step-4:

Step 4: Science!
----------------

Congratulations, you're now ready to use Trident! Please refer to the
documentation for how to use it with your data or with one of our sample
datasets. Please join our :ref:`mailing list
Congratulations, you're now ready to use Trident! Please refer to the
documentation for how to use it with your data or with one of our sample
datasets. Please join our :ref:`mailing list
<mailing-list>` for announcements and when new features are added to the code.

.. _manual-config:
Expand All @@ -148,35 +143,35 @@ Manually Installing your Ionization Table

If for some reason you are unable to install the config file and ionization
table data automatically, you must set it up manually. When Trident runs,
it looks for a configuration file called ``config.tri`` in the
``$HOME/.trident`` directory or alternatively in the current working
directory (for users lacking write access to their ``$HOME`` directories).
This configuration file is simple in that it tells Trident a few things about
your install including the location and filename of your desired ionization
table. Manually create a text file called ``config.tri`` with contents
it looks for a configuration file called ``config.tri`` in the
``$HOME/.trident`` directory or alternatively in the current working
directory (for users lacking write access to their ``$HOME`` directories).
This configuration file is simple in that it tells Trident a few things about
your install including the location and filename of your desired ionization
table. Manually create a text file called ``config.tri`` with contents
following the form::

[Trident]
ion_table_dir = ~/.trident
ion_table_file = hm2012_hr.h5

To manually obtain an ion table datafile, download and gunzip one from:
http://trident-project.org/data/ion_table . While the ``config.tri`` file needs
http://trident-project.org/data/ion_table . While the ``config.tri`` file needs
to exist in your ``$HOME/.trident`` directory or in the working directory
when you import trident, the ion_table datafile can exist anywhere on the
file system. Just assure that the config file points to the proper location
when you import trident, the ion_table datafile can exist anywhere on the
file system. Just assure that the config file points to the proper location
and filename of the ion table datafile.

Now, to confirm everything is working properly, verify your installation
following :ref:`step-3`. If this fails or you have additional problems,
following :ref:`step-3`. If this fails or you have additional problems,
please contact our mailing list.

.. _uninstallation:

Uninstallation or Switching Code Versions
-----------------------------------------

Uninstallation of the Trident source code is easy. If you installed the
Uninstallation of the Trident source code is easy. If you installed the
stable version of the code via pip, just run::

$ pip uninstall trident
Expand All @@ -192,8 +187,8 @@ If you want to switch between the two stable and development versions, just
version as described in :ref:`install-trident`

To fully remove the code from your system, remember to remove any ion table
datafiles you may have downloaded in your ``$HOME/.trident`` directory,
and follow the instructions for how to `uninstall yt
datafiles you may have downloaded in your ``$HOME/.trident`` directory,
and follow the instructions for how to `uninstall yt
<http://yt-project.org/docs/dev/installing.html>`_.

.. _updating:
Expand All @@ -202,12 +197,12 @@ Updating to the Latest Version
------------------------------

If you want more recent features, you should periodically update your Trident
codebase.
codebase.

Updating to the Latest Stable Release
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you installed the "stable" version of the code using pip, then
If you installed the "stable" version of the code using pip, then
you can easily update your trident and yt installations::

$ pip install -U trident
Expand All @@ -224,6 +219,6 @@ involved::
$ pip install -e .
$ yt update

For more information on updating your yt installation, see the `yt update
instructions
For more information on updating your yt installation, see the `yt update
instructions
<http://yt-project.org/docs/dev/installing.html#updating-yt-and-its-dependencies>`_.
8 changes: 1 addition & 7 deletions tests/test_config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,7 @@

from trident.config import \
trident, \
trident_path, \
create_config, \
parse_config
trident_path

def test_banner():
"""
Expand All @@ -28,7 +26,3 @@ def test_path():
Tests that the trident path is working ok.
"""
trident_path()

# Need to make a test_config but this necessitates changing the config
# code around a bunch.

10 changes: 4 additions & 6 deletions trident/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,9 @@

__version__ = "1.3.dev1"

# Must run import_check() before anything else is imported to avoid
# astropy error when importing trident in trident package directory
from trident.utilities import import_check
import_check()

from trident.config import \
parse_config, \
create_config, \
auto_config, \
trident, \
trident_path, \
verify
Expand Down Expand Up @@ -73,3 +68,6 @@

# Making installation path global
path = trident_path()

# Check that configuration is correct
parse_config(first_parse=True)
Loading