Debian Codegraph @

docs/tutorials/speed.rst

raw
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.