| 1 |
.. _speed: |
| 2 |
|
| 3 |
********************* |
| 4 |
Speeding up astroplan |
| 5 |
********************* |
| 6 |
|
| 7 |
Some users of astroplan may find it useful to trade-off a bit of precision |
| 8 |
in the rise/set/transit times of targets in exchange for computational |
| 9 |
efficiency. In this short tutorial, we show you how to speed up astroplan |
| 10 |
in exchange for a bit of time precision, which is especially useful when |
| 11 |
planning many observations over a long period of time. |
| 12 |
|
| 13 |
Rise/set/transit times |
| 14 |
====================== |
| 15 |
|
| 16 |
The rise, set, and transit time methods on the `~astroplan.Observer` object |
| 17 |
take an optional keyword argument called ``n_grid_points`` as of astroplan |
| 18 |
version 0.6 (in earlier versions of astroplan, ``n_grid_points`` is fixed to |
| 19 |
150). To understand ``n_grid_points`` you first need to know how target |
| 20 |
rise/set/transit times are computed in astroplan. |
| 21 |
|
| 22 |
Astroplan computes rise/set times relative to a given reference time by |
| 23 |
computing the altitude of the target on a grid which spans a period of 24 hours |
| 24 |
before/after the reference time. The grid is then searched for |
| 25 |
horizon-crossings, and astroplan interpolates between the two nearest-to-zero |
| 26 |
altitudes to approximate the target rise/set times. |
| 27 |
|
| 28 |
The ``n_grid_points`` keyword argument dictates the number of grid points on |
| 29 |
which to compute the target altitude. The larger the ``n_grid_points``, the |
| 30 |
more precise the rise/set/transit time will be, but the operation also becomes |
| 31 |
more computationally expensive. As a general rule of thumb, if you choose |
| 32 |
``n_grid_points=150`` your rise/set time precisions will be precise to better |
| 33 |
than one minute; this is the default if you don't specify ``n_grid_points``. If |
| 34 |
you choose ``n_grid_points=10`` you'll get significantly faster rise/set time |
| 35 |
computations, but your precision degrades to better than five minutes. |
| 36 |
|
| 37 |
Examples |
| 38 |
======== |
| 39 |
|
| 40 |
Let's see some simple examples. We can compute a very accurate rise time for |
| 41 |
Sirius over Apache Point Observatory, by specifying ``n_grid_points=1000``: |
| 42 |
|
| 43 |
.. code-block:: python |
| 44 |
|
| 45 |
>>> from astroplan import Observer, FixedTarget |
| 46 |
>>> from astropy.time import Time |
| 47 |
|
| 48 |
>>> time = Time('2019-01-01 00:00') |
| 49 |
>>> sirius = FixedTarget.from_name('Sirius') |
| 50 |
>>> apo = Observer.at_site('APO') |
| 51 |
|
| 52 |
>>> rise_time_accurate = apo.target_rise_time(time, sirius, n_grid_points=1000) |
| 53 |
>>> rise_time_accurate.iso # doctest: +SKIP |
| 54 |
'2019-01-01 01:52:13.393' |
| 55 |
|
| 56 |
That's the rise time computed on a grid of 1000 altitudes in a 24 hour period, |
| 57 |
so it should be very accurate, but we can run the ``timeit`` function on the |
| 58 |
above code snippet to see how slow this is: |
| 59 |
|
| 60 |
.. code-block:: shell |
| 61 |
|
| 62 |
290 ms ± 4.6 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) |
| 63 |
|
| 64 |
Now let's compute a lower precision, but much faster rise time, using ``N=10`` |
| 65 |
this time: |
| 66 |
|
| 67 |
.. code-block:: python |
| 68 |
|
| 69 |
>>> rise_time_fast = apo.target_rise_time(time, sirius, n_grid_points=10) |
| 70 |
>>> rise_time_fast.iso # doctest: +SKIP |
| 71 |
'2019-01-01 01:54:09.946' |
| 72 |
|
| 73 |
And timing the above snippet, we find: |
| 74 |
|
| 75 |
.. code-block:: shell |
| 76 |
|
| 77 |
27.3 ms ± 709 µs per loop (mean ± std. dev. of 7 runs, 10 loops each) |
| 78 |
|
| 79 |
You can see that the rise time returned by |
| 80 |
`~astroplan.Observer.target_rise_time` with ``n_grid_points=10`` is only two |
| 81 |
minutes different from the prediction with ``n_grid_points=1000``, so it looks |
| 82 |
like we haven't lost much precision despite the drastically different number of |
| 83 |
grid points and an order-of-magnitude speedup. |