././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1695224569.999814 astroplan-0.9.1/0000755001274200020070000000000014502611372014553 5ustar00bmmorrisSTSCI\science././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1695224569.9800467 astroplan-0.9.1/.github/0000755001274200020070000000000014502611372016113 5ustar00bmmorrisSTSCI\science././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1695224569.9837081 astroplan-0.9.1/.github/workflows/0000755001274200020070000000000014502611372020150 5ustar00bmmorrisSTSCI\science././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1685929213.0 astroplan-0.9.1/.github/workflows/ci_tests.yml0000644001274200020070000000460614437236375022533 0ustar00bmmorrisSTSCI\science# GitHub Actions workflow for testing and continuous integration. # # This file performs testing using tox and tox.ini to define and configure the test environments. name: CI Tests on: push: branches: - main pull_request: branches: # only build on PRs against 'main' if you need to further limit when CI is run. - main concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: # Github Actions supports ubuntu, windows, and macos virtual environments: # https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners ci_tests: name: ${{ matrix.name }} runs-on: ${{ matrix.os }} strategy: matrix: include: - name: Code style checks os: ubuntu-latest python: 3.x toxenv: codestyle - name: Python 3.7 with minimal dependencies os: ubuntu-latest python: 3.7 toxenv: py37-test - name: OS X - Python 3.9 with minimal dependencies os: macos-latest python: 3.9 toxenv: py39-test - name: Windows - Python 3.11 with all optional dependencies os: windows-latest python: 3.11 toxenv: py11-test-alldeps - name: Python 3.11 with remote data, all dependencies, and coverage os: ubuntu-latest python: 3.11 toxenv: py11-test-alldeps-cov toxposargs: --remote-data - name: Python 3.11 with latest dev versions of key dependencies os: ubuntu-latest python: 3.11 toxenv: py11-test-devdeps - name: Test building of Sphinx docs os: ubuntu-latest python: 3.x toxenv: build_docs steps: - name: Checkout code uses: actions/checkout@v1 with: fetch-depth: 0 - name: Set up python ${{ matrix.python }} on ${{ matrix.os }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python }} - name: Install base dependencies run: | python -m pip install --upgrade pip python -m pip install tox codecov - name: Install graphviz dependency if: ${{ contains(matrix.toxenv, 'build_docs') }} run: sudo apt-get -y install graphviz - name: Test with tox run: | tox -e ${{ matrix.toxenv }} ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511824.0 astroplan-0.9.1/.gitignore0000644001274200020070000000115614321330620016537 0ustar00bmmorrisSTSCI\science# Compiled files *.py[cod] *.a *.o *.so __pycache__ # Ignore .c files by default to avoid including generated code. If you want to # add a non-generated .c extension, use `git add -f filename.c`. *.c # Other generated files */version.py */cython_version.py htmlcov .coverage MANIFEST .ipynb_checkpoints # Sphinx docs/api docs/_build # Eclipse editor project files .project .pydevproject .settings # Pycharm editor project files .idea # Packages/installer info *.egg *.egg-info dist build eggs parts bin var sdist develop-eggs .installed.cfg distribute-*.tar.gz # Other .cache .tox .*.sw[op] *~ # Mac OSX .DS_Store ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511896.0 astroplan-0.9.1/.gitmodules0000644001274200020070000000000014321330730016711 0ustar00bmmorrisSTSCI\science././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1679013205.0 astroplan-0.9.1/.readthedocs.yml0000644001274200020070000000120114404732525017640 0ustar00bmmorrisSTSCI\science# .readthedocs.yml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required version: 2 # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py # Optionally build your docs in additional formats such as PDF formats: - pdf build: os: ubuntu-20.04 apt_packages: - graphviz tools: python: "3.9" # Optionally set the version of Python and requirements required to build your docs python: install: - requirements: docs/rtd-pip-requirements - method: pip path: . extra_requirements: - docs ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1695223789.0 astroplan-0.9.1/CHANGES.rst0000644001274200020070000000672014502607755016374 0ustar00bmmorrisSTSCI\science0.9.1 (2023-09-20) ------------------ - Fix bug when ``FixedTarget`` objects are passed to methods that calculate lunar coordinates. [#568] 0.9 (2023-07-27) ---------------- - Fix time range in ``months_observable`` to not be only in 2014. Function now accepts argument ``time_range`` and defaults to the current year. [#458] - Fix ``Observer`` not having longtitude, latitude, and elevation parameters as class attributes. They are now properties calculated from the ``location``. - Documentation revisions and theme update [#563] 0.8 (2021-01-26) ---------------- - Fix Read The Docs compatibility [#497] - Move to APE 17 infrastructure, change to github actions [#493] - Update conda channel in favor of conda-forge [#491] - Fix for astropy cache compatibility [#481] 0.7 (2020-10-27) ---------------- - Fix compatibility with Astropy 4.X 0.6 (2019-10-08) ---------------- - Added documentation for reproducing MMTO sun rise/set times [#434] - Deprecation of ``MAGIC_TIME`` variable, which used to be returned for targets that don't rise or set [#435] - Replace deprecated astroquery service [#431] - Fix for the broken IERS patch [#418, #425] - Add ``GalacticLatitudeConstraint`` to constrain the galactic latitudes of targets. This can be useful for planning surveys for which crowding due to Galactic point sources is an issue. [#413] - Add ``n_grid_points`` keyword argument to rise/set/transit functions which allows usersto trade off precision for speed. [#424] 0.5 (2019-07-08) ---------------- - ``observability_table`` now accepts scalars as ``time_range`` arguments, and gives ``'time observable'`` in this case in the resulting table. [#350] - Bug fixes [#414, #412, #407, #401] 0.4 (2017-10-23) ---------------- - Added new ``eclipsing`` module for eclipsing binaries and transiting exoplanets [#315] - Fixes for compatibility with astropy Quantity object updates [#336] - Better PEP8 compatibility [#335] - Using travis build stages [#330] 0.3 (2017-09-02) ---------------- - ``Observer.altaz`` and ``Constraint.__call__`` no longer returns an (MxN) grid of results when called with M ``target``s and N ``times``. Instead, we attempt to broadcast the time and target shapes, and an error is raised if this is not possible. This change breaks backwards compatibility but an optional argument ``grid_times_targets`` has been added to these methods. If set to True, the old behaviour is recovered. All ``Observer`` methods for which it is relevant have this optional argument. - Updates for compatibility with astropy v2.0 coordinates implementation [#311], updates to astropy-helpers [#309], fix pytest version [#312] 0.2.1 (2016-04-27) ------------------ - Internal changes to the way calculations are done means that astropy>=1.3 is required [#285] - Fixed bug when scheduling block list is empty [#298] - Fixed bug in Transitioner object when no transition needed [#295] - Update to astropy-helpers 1.3.1 [#294] and compatibility fixes for astropy 1.3 [#283] 0.2 (2016-09-20) ---------------- - Fixed bug arising from changes to distutils.ConfigParser [#177, #187, #191] - Removed the sites module from astroplan, since it was ported to astropy [#168] - Removed dependence on PyEphem, now using jplephem for the solar system ephemeris [#167] - New API for scheduling observations (still in development) - New ``plot_finder_image`` function makes quick finder charts [#115] - Updates to astropy helpers and the package template [#177, #180] ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1673375923.0 astroplan-0.9.1/CITATION.bib0000644001274200020070000000143314357330263016451 0ustar00bmmorrisSTSCI\science@ARTICLE{astroplan2018, author = {{Morris}, B.~M. and {Tollerud}, E. and {Sip{\H o}cz}, B. and {Deil}, C. and {Douglas}, S.~T. and {Berlanga Medina}, J. and {Vyhmeister}, K. and {Smith}, T.~R. and {Littlefair}, S. and {Price-Whelan}, A.~M. and {Gee}, W.~T. and {Jeschke}, E.}, title = "{astroplan: An Open Source Observation Planning Package in Python}", journal = {\aj}, archivePrefix = "arXiv", eprint = {1712.09631}, primaryClass = "astro-ph.IM", keywords = {methods: numerical, methods: observational }, year = 2018, month = mar, volume = 155, eid = {128}, pages = {128}, doi = {10.3847/1538-3881/aaa47e}, adsurl = {http://adsabs.harvard.edu/abs/2018AJ....155..128M}, adsnote = {Provided by the SAO/NASA Astrophysics Data System} } ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511824.0 astroplan-0.9.1/LICENSE.rst0000644001274200020070000000273114321330620016363 0ustar00bmmorrisSTSCI\scienceCopyright (c) 2015-2017, Astroplan Developers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Astropy Team nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511824.0 astroplan-0.9.1/LONG_DESCRIPTION.rst0000644001274200020070000000073514321330620017705 0ustar00bmmorrisSTSCI\science* Code: https://github.com/astropy/astroplan * Docs: https://astroplan.readthedocs.io/ **astroplan** is an open source (BSD licensed) observation planning package for astronomers that can help you plan for everything but the clouds. It is an in-development `Astropy `__ `affiliated package `__ that seeks to make your life as an observational astronomer a little less infuriating. Contributions welcome! ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1673375923.0 astroplan-0.9.1/MANIFEST.in0000644001274200020070000000052314357330263016316 0ustar00bmmorrisSTSCI\scienceinclude LICENSE.rst include README.rst include CHANGES.rst include ez_setup.py include ah_bootstrap.py include setup.cfg recursive-include *.pyx *.c *.pxd recursive-include docs * recursive-include licenses * recursive-include cextern * recursive-include scripts * prune build prune docs/_build prune docs/api global-exclude *.pyc *.o ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1695224569.999701 astroplan-0.9.1/PKG-INFO0000644001274200020070000000600214502611372015646 0ustar00bmmorrisSTSCI\scienceMetadata-Version: 2.1 Name: astroplan Version: 0.9.1 Summary: Observation planning package for astronomers Home-page: https://github.com/astropy/astroplan Author: Astroplan developers Author-email: astropy-dev@googlegroups.com License: BSD Requires-Python: >=3.7 Description-Content-Type: text/x-rst License-File: LICENSE.rst Requires-Dist: numpy>=1.17 Requires-Dist: astropy>=4 Requires-Dist: pytz Requires-Dist: six Provides-Extra: all Requires-Dist: matplotlib>=1.4; extra == "all" Requires-Dist: astroquery; extra == "all" Provides-Extra: test Requires-Dist: pytest-astropy; extra == "test" Requires-Dist: pytest-mpl; extra == "test" Provides-Extra: docs Requires-Dist: sphinx-astropy[confv2]; extra == "docs" Requires-Dist: sphinx-rtd-theme; extra == "docs" Requires-Dist: matplotlib>=1.4; extra == "docs" Requires-Dist: astroquery; extra == "docs" Provides-Extra: plotting Requires-Dist: astroquery; extra == "plotting" Requires-Dist: matplotlib>=1.4; extra == "plotting" astroplan ========= Observation planning package for astronomers * Code: https://github.com/astropy/astroplan * Docs: https://astroplan.readthedocs.io/ * License: BSD-3 .. image:: https://readthedocs.org/projects/astroplan/badge/?version=latest :target: https://astroplan.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: http://img.shields.io/badge/arXiv-1709.03913-red.svg?style=flat :target: https://arxiv.org/abs/1712.09631 :alt: arXiv paper .. image:: https://github.com/astropy/astroplan/workflows/CI%20Tests/badge.svg :target: https://github.com/astropy/astroplan/actions .. image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat :target: http://www.astropy.org/ .. image:: http://img.shields.io/pypi/v/astroplan.svg?text=version :target: https://pypi.python.org/pypi/astroplan/ :alt: Latest release Attribution +++++++++++ If you use astroplan in your work, please cite `Morris et al. 2018 `_: .. code :: bibtex @ARTICLE{2018AJ....155..128M, author = {{Morris}, Brett M. and {Tollerud}, Erik and {Sip{\H{o}}cz}, Brigitta and {Deil}, Christoph and {Douglas}, Stephanie T. and {Berlanga Medina}, Jazmin and {Vyhmeister}, Karl and {Smith}, Toby R. and {Littlefair}, Stuart and {Price-Whelan}, Adrian M. and {Gee}, Wilfred T. and {Jeschke}, Eric}, title = "{astroplan: An Open Source Observation Planning Package in Python}", journal = {\aj}, keywords = {methods: numerical, methods: observational, Astrophysics - Instrumentation and Methods for Astrophysics}, year = 2018, month = mar, volume = {155}, number = {3}, eid = {128}, pages = {128}, doi = {10.3847/1538-3881/aaa47e}, archivePrefix = {arXiv}, eprint = {1712.09631}, primaryClass = {astro-ph.IM}, adsurl = {https://ui.adsabs.harvard.edu/abs/2018AJ....155..128M}, adsnote = {Provided by the SAO/NASA Astrophysics Data System} } ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1690480352.0 astroplan-0.9.1/README.rst0000644001274200020070000000405714460527340016254 0ustar00bmmorrisSTSCI\scienceastroplan ========= Observation planning package for astronomers * Code: https://github.com/astropy/astroplan * Docs: https://astroplan.readthedocs.io/ * License: BSD-3 .. image:: https://readthedocs.org/projects/astroplan/badge/?version=latest :target: https://astroplan.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: http://img.shields.io/badge/arXiv-1709.03913-red.svg?style=flat :target: https://arxiv.org/abs/1712.09631 :alt: arXiv paper .. image:: https://github.com/astropy/astroplan/workflows/CI%20Tests/badge.svg :target: https://github.com/astropy/astroplan/actions .. image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat :target: http://www.astropy.org/ .. image:: http://img.shields.io/pypi/v/astroplan.svg?text=version :target: https://pypi.python.org/pypi/astroplan/ :alt: Latest release Attribution +++++++++++ If you use astroplan in your work, please cite `Morris et al. 2018 `_: .. code :: bibtex @ARTICLE{2018AJ....155..128M, author = {{Morris}, Brett M. and {Tollerud}, Erik and {Sip{\H{o}}cz}, Brigitta and {Deil}, Christoph and {Douglas}, Stephanie T. and {Berlanga Medina}, Jazmin and {Vyhmeister}, Karl and {Smith}, Toby R. and {Littlefair}, Stuart and {Price-Whelan}, Adrian M. and {Gee}, Wilfred T. and {Jeschke}, Eric}, title = "{astroplan: An Open Source Observation Planning Package in Python}", journal = {\aj}, keywords = {methods: numerical, methods: observational, Astrophysics - Instrumentation and Methods for Astrophysics}, year = 2018, month = mar, volume = {155}, number = {3}, eid = {128}, pages = {128}, doi = {10.3847/1538-3881/aaa47e}, archivePrefix = {arXiv}, eprint = {1712.09631}, primaryClass = {astro-ph.IM}, adsurl = {https://ui.adsabs.harvard.edu/abs/2018AJ....155..128M}, adsnote = {Provided by the SAO/NASA Astrophysics Data System} } ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1695224569.9876816 astroplan-0.9.1/astroplan/0000755001274200020070000000000014502611372016556 5ustar00bmmorrisSTSCI\science././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511824.0 astroplan-0.9.1/astroplan/__init__.py0000644001274200020070000000217314321330620020663 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst """ astroplan is an open source (BSD licensed) observation planning package for astronomers that can help you plan for everything but the clouds. It is an in-development `Astropy `__ `affiliated package `__ that seeks to make your life as an observational astronomer a little less infuriating. * Code: https://github.com/astropy/astroplan * Docs: https://astroplan.readthedocs.io/ """ # Affiliated packages may add whatever they like to this file, but # should keep this content at the top. # ---------------------------------------------------------------------------- from ._astropy_init import * # ---------------------------------------------------------------------------- # For egg_info test builds to pass, put package imports here. if not _ASTROPY_SETUP_: from .utils import * from .observer import * from .target import * from .exceptions import * from .moon import * from .constraints import * from .scheduling import * from .periodic import * download_IERS_A() ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1665511896.0 astroplan-0.9.1/astroplan/_astropy_init.py0000644001274200020070000000114514321330730022007 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst __all__ = ['__version__'] # this indicates whether or not we are in the package's setup.py try: _ASTROPY_SETUP_ except NameError: import builtins builtins._ASTROPY_SETUP_ = False try: from .version import version as __version__ except ImportError: __version__ = '' if not _ASTROPY_SETUP_: # noqa import os # Create the test function for self test from astropy.tests.runner import TestRunner test = TestRunner.make_test_runner_in(os.path.dirname(__file__)) test.__test__ = False __all__ += ['test'] ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1690478983.0 astroplan-0.9.1/astroplan/conftest.py0000644001274200020070000000313514460524607020766 0ustar00bmmorrisSTSCI\science""" This file contains functions that configure py.test like astropy but with additions for astroplan. Py.test looks for specially-named functions (like ``pytest_configure``) and uses those to configure itself. Here, we want to keep the behavior of astropy while *adding* more for astroplan. To do that, in the functions below, we first invoke the functions from astropy, and then after that do things specific to astroplan. But we also want astropy functionality for any functions we have *not* overriden, so that's why the ``import *`` happens at the top. """ try: from pytest_astropy_header.display import PYTEST_HEADER_MODULES, TESTED_VERSIONS except ImportError: # In case this plugin is not installed PYTEST_HEADER_MODULES = {} TESTED_VERSIONS = {} # We do this to pick up the test header report even when using LTS astropy try: from astropy.tests.pytest_plugins import pytest_report_header # noqa except ImportError: pass import os # This is to figure out the affiliated package version, rather than # using Astropy's try: from .version import version except ImportError: version = 'dev' packagename = os.path.basename(os.path.dirname(__file__)) TESTED_VERSIONS[packagename] = version # Define list of packages for which to display version numbers in the test log try: PYTEST_HEADER_MODULES['Astropy'] = 'astropy' PYTEST_HEADER_MODULES['pytz'] = 'pytz' PYTEST_HEADER_MODULES['pyephem'] = 'ephem' PYTEST_HEADER_MODULES['matplotlib'] = 'matplotlib' PYTEST_HEADER_MODULES['pytest-mpl'] = 'pytest_mpl' del PYTEST_HEADER_MODULES['h5py'] except KeyError: pass ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1695223658.0 astroplan-0.9.1/astroplan/constraints.py0000644001274200020070000014170014502607552021507 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst """ Specify and constraints to determine which targets are observable for an observer. """ from __future__ import (absolute_import, division, print_function, unicode_literals) # Standard library from abc import ABCMeta, abstractmethod import datetime import time import warnings # Third-party from astropy.time import Time import astropy.units as u from astropy.coordinates import get_body, get_sun, Galactic, SkyCoord from astropy import table import numpy as np from numpy.lib.stride_tricks import as_strided # Package from .moon import moon_illumination from .utils import time_grid_from_range from .target import get_skycoord from .exceptions import MissingConstraintWarning __all__ = ["AltitudeConstraint", "AirmassConstraint", "AtNightConstraint", "is_observable", "is_always_observable", "time_grid_from_range", "GalacticLatitudeConstraint", "SunSeparationConstraint", "MoonSeparationConstraint", "MoonIlluminationConstraint", "LocalTimeConstraint", "PrimaryEclipseConstraint", "SecondaryEclipseConstraint", "Constraint", "TimeConstraint", "observability_table", "months_observable", "max_best_rescale", "min_best_rescale", "PhaseConstraint", "is_event_observable"] _current_year = time.localtime().tm_year # needed for backward compatibility _current_year_time_range = Time( # needed for backward compatibility [str(_current_year) + '-01-01', str(_current_year) + '-12-31'] ) def _make_cache_key(times, targets): """ Make a unique key to reference this combination of ``times`` and ``targets``. Often, we wish to store expensive calculations for a combination of ``targets`` and ``times`` in a cache on an ``observer``` object. This routine will provide an appropriate, hashable, key to store these calculations in a dictionary. Parameters ---------- times : `~astropy.time.Time` Array of times on which to test the constraint. targets : `~astropy.coordinates.SkyCoord` Target or list of targets. Returns ------- cache_key : tuple A hashable tuple for use as a cache key """ # make a tuple from times try: timekey = tuple(times.jd) + times.shape except BaseException: # must be scalar timekey = (times.jd,) # make hashable thing from targets coords try: if hasattr(targets, 'frame'): # treat as a SkyCoord object. Accessing the longitude # attribute of the frame data should be unique and is # quicker than accessing the ra attribute. targkey = tuple(targets.frame.data.lon.value.ravel()) + targets.shape else: # assume targets is a string. targkey = (targets,) except BaseException: targkey = (targets.frame.data.lon,) return timekey + targkey def _get_altaz(times, observer, targets, force_zero_pressure=False): """ Calculate alt/az for ``target`` at times linearly spaced between the two times in ``time_range`` with grid spacing ``time_resolution`` for ``observer``. Cache the result on the ``observer`` object. Parameters ---------- times : `~astropy.time.Time` Array of times on which to test the constraint. targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets. observer : `~astroplan.Observer` The observer who has constraints ``constraints``. force_zero_pressure : bool Forcefully use 0 pressure. Returns ------- altaz_dict : dict Dictionary containing two key-value pairs. (1) 'times' contains the times for the alt/az computations, (2) 'altaz' contains the corresponding alt/az coordinates at those times. """ if not hasattr(observer, '_altaz_cache'): observer._altaz_cache = {} # convert times, targets to tuple for hashing aakey = _make_cache_key(times, targets) if aakey not in observer._altaz_cache: try: if force_zero_pressure: observer_old_pressure = observer.pressure observer.pressure = 0 altaz = observer.altaz(times, targets, grid_times_targets=False) observer._altaz_cache[aakey] = dict(times=times, altaz=altaz) finally: if force_zero_pressure: observer.pressure = observer_old_pressure return observer._altaz_cache[aakey] def _get_moon_data(times, observer, force_zero_pressure=False): """ Calculate moon altitude az and illumination for an array of times for ``observer``. Cache the result on the ``observer`` object. Parameters ---------- times : `~astropy.time.Time` Array of times on which to test the constraint. observer : `~astroplan.Observer` The observer who has constraints ``constraints``. force_zero_pressure : bool Forcefully use 0 pressure. Returns ------- moon_dict : dict Dictionary containing three key-value pairs. (1) 'times' contains the times for the computations, (2) 'altaz' contains the corresponding alt/az coordinates at those times and (3) contains the moon illumination for those times. """ if not hasattr(observer, '_moon_cache'): observer._moon_cache = {} # convert times to tuple for hashing aakey = _make_cache_key(times, 'moon') if aakey not in observer._moon_cache: try: if force_zero_pressure: observer_old_pressure = observer.pressure observer.pressure = 0 altaz = observer.moon_altaz(times) illumination = np.array(moon_illumination(times)) observer._moon_cache[aakey] = dict(times=times, illum=illumination, altaz=altaz) finally: if force_zero_pressure: observer.pressure = observer_old_pressure return observer._moon_cache[aakey] def _get_meridian_transit_times(times, observer, targets): """ Calculate next meridian transit for an array of times for ``targets`` and ``observer``. Cache the result on the ``observer`` object. Parameters ---------- times : `~astropy.time.Time` Array of times on which to test the constraint observer : `~astroplan.Observer` The observer who has constraints ``constraints`` targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets Returns ------- time_dict : dict Dictionary containing a key-value pair. 'times' contains the meridian_transit times. """ if not hasattr(observer, '_meridian_transit_cache'): observer._meridian_transit_cache = {} # convert times to tuple for hashing aakey = _make_cache_key(times, targets) if aakey not in observer._meridian_transit_cache: meridian_transit_times = observer.target_meridian_transit_time(times, targets) observer._meridian_transit_cache[aakey] = dict(times=meridian_transit_times) return observer._meridian_transit_cache[aakey] @abstractmethod class Constraint(object): """ Abstract class for objects defining observational constraints. """ __metaclass__ = ABCMeta def __call__(self, observer, targets, times=None, time_range=None, time_grid_resolution=0.5*u.hour, grid_times_targets=False): """ Compute the constraint for this class Parameters ---------- observer : `~astroplan.Observer` the observation location from which to apply the constraints targets : sequence of `~astroplan.Target` The targets on which to apply the constraints. times : `~astropy.time.Time` The times to compute the constraint. WHAT HAPPENS WHEN BOTH TIMES AND TIME_RANGE ARE SET? time_range : `~astropy.time.Time` (length = 2) Lower and upper bounds on time sequence. time_grid_resolution : `~astropy.units.quantity` Time-grid spacing grid_times_targets : bool if True, grids the constraint result with targets along the first index and times along the second. Otherwise, we rely on broadcasting the shapes together using standard numpy rules. Returns ------- constraint_result : 1D or 2D array of float or bool The constraints. If 2D with targets along the first index and times along the second. """ if times is None and time_range is not None: times = time_grid_from_range(time_range, time_resolution=time_grid_resolution) if grid_times_targets: targets = get_skycoord(targets) # TODO: these broadcasting operations are relatively slow # but there is potential for huge speedup if the end user # disables gridding and re-shapes the coords themselves # prior to evaluating multiple constraints. if targets.isscalar: # ensure we have a (1, 1) shape coord targets = SkyCoord(np.tile(targets, 1))[:, np.newaxis] else: targets = targets[..., np.newaxis] times, targets = observer._preprocess_inputs(times, targets, grid_times_targets=False) result = self.compute_constraint(times, observer, targets) # make sure the output has the same shape as would result from # broadcasting times and targets against each other if targets is not None: # broadcasting times v targets is slow due to # complex nature of these objects. We make # to simple numpy arrays of the same shape and # broadcast these to find the correct shape shp1, shp2 = times.shape, targets.shape x = np.array([1]) a = as_strided(x, shape=shp1, strides=[0] * len(shp1)) b = as_strided(x, shape=shp2, strides=[0] * len(shp2)) output_shape = np.broadcast(a, b).shape if output_shape != np.array(result).shape: result = np.broadcast_to(result, output_shape) return result @abstractmethod def compute_constraint(self, times, observer, targets): """ Actually do the real work of computing the constraint. Subclasses override this. Parameters ---------- times : `~astropy.time.Time` The times to compute the constraint observer : `~astroplan.Observer` the observaton location from which to apply the constraints targets : sequence of `~astroplan.Target` The targets on which to apply the constraints. Returns ------- constraint_result : 2D array of float or bool The constraints, with targets along the first index and times along the second. """ # Should be implemented on each subclass of Constraint raise NotImplementedError class AltitudeConstraint(Constraint): """ Constrain the altitude of the target. .. note:: This can misbehave if you try to constrain negative altitudes, as the `~astropy.coordinates.AltAz` frame tends to mishandle negative Parameters ---------- min : `~astropy.units.Quantity` or `None` Minimum altitude of the target (inclusive). `None` indicates no limit. max : `~astropy.units.Quantity` or `None` Maximum altitude of the target (inclusive). `None` indicates no limit. boolean_constraint : bool If True, the constraint is treated as a boolean (True for within the limits and False for outside). If False, the constraint returns a float on [0, 1], where 0 is the min altitude and 1 is the max. """ def __init__(self, min=None, max=None, boolean_constraint=True): if min is None: self.min = -90*u.deg else: self.min = min if max is None: self.max = 90*u.deg else: self.max = max self.boolean_constraint = boolean_constraint def compute_constraint(self, times, observer, targets): cached_altaz = _get_altaz(times, observer, targets) alt = cached_altaz['altaz'].alt if self.boolean_constraint: lowermask = self.min <= alt uppermask = alt <= self.max return lowermask & uppermask else: return max_best_rescale(alt, self.min, self.max, greater_than_max=0) class AirmassConstraint(AltitudeConstraint): """ Constrain the airmass of a target. In the current implementation the airmass is approximated by the secant of the zenith angle. .. note:: The ``max`` and ``min`` arguments appear in the order (max, min) in this initializer to support the common case for users who care about the upper limit on the airmass (``max``) and not the lower limit. Parameters ---------- max : float or `None` Maximum airmass of the target. `None` indicates no limit. min : float or `None` Minimum airmass of the target. `None` indicates no limit. boolean_contstraint : bool Examples -------- To create a constraint that requires the airmass be "better than 2", i.e. at a higher altitude than airmass=2:: AirmassConstraint(2) """ def __init__(self, max=None, min=1, boolean_constraint=True): self.min = min self.max = max self.boolean_constraint = boolean_constraint def compute_constraint(self, times, observer, targets): cached_altaz = _get_altaz(times, observer, targets) secz = cached_altaz['altaz'].secz.value if self.boolean_constraint: if self.min is None and self.max is not None: mask = secz <= self.max elif self.max is None and self.min is not None: mask = self.min <= secz elif self.min is not None and self.max is not None: mask = (self.min <= secz) & (secz <= self.max) else: raise ValueError("No max and/or min specified in " "AirmassConstraint.") return mask else: if self.max is None: raise ValueError("Cannot have a float AirmassConstraint if max is None.") else: mx = self.max mi = 1 if self.min is None else self.min # values below 1 should be disregarded return min_best_rescale(secz, mi, mx, less_than_min=0) class AtNightConstraint(Constraint): """ Constrain the Sun to be below ``horizon``. """ @u.quantity_input(horizon=u.deg) def __init__(self, max_solar_altitude=0*u.deg, force_pressure_zero=True): """ Parameters ---------- max_solar_altitude : `~astropy.units.Quantity` The altitude of the sun below which it is considered to be "night" (inclusive). force_pressure_zero : bool (optional) Force the pressure to zero for solar altitude calculations. This avoids errors in the altitude of the Sun that can occur when the Sun is below the horizon and the corrections for atmospheric refraction return nonsense values. """ self.max_solar_altitude = max_solar_altitude self.force_pressure_zero = force_pressure_zero @classmethod def twilight_civil(cls, **kwargs): """ Consider nighttime as time between civil twilights (-6 degrees). """ return cls(max_solar_altitude=-6*u.deg, **kwargs) @classmethod def twilight_nautical(cls, **kwargs): """ Consider nighttime as time between nautical twilights (-12 degrees). """ return cls(max_solar_altitude=-12*u.deg, **kwargs) @classmethod def twilight_astronomical(cls, **kwargs): """ Consider nighttime as time between astronomical twilights (-18 degrees). """ return cls(max_solar_altitude=-18*u.deg, **kwargs) def _get_solar_altitudes(self, times, observer, targets): if not hasattr(observer, '_altaz_cache'): observer._altaz_cache = {} aakey = _make_cache_key(times, 'sun') if aakey not in observer._altaz_cache: try: if self.force_pressure_zero: observer_old_pressure = observer.pressure observer.pressure = 0 # find solar altitude at these times altaz = observer.altaz(times, get_sun(times)) altitude = altaz.alt # cache the altitude observer._altaz_cache[aakey] = dict(times=times, altitude=altitude) finally: if self.force_pressure_zero: observer.pressure = observer_old_pressure else: altitude = observer._altaz_cache[aakey]['altitude'] return altitude def compute_constraint(self, times, observer, targets): solar_altitude = self._get_solar_altitudes(times, observer, targets) mask = solar_altitude <= self.max_solar_altitude return mask class GalacticLatitudeConstraint(Constraint): """ Constrain the distance between the Galactic plane and some targets. """ def __init__(self, min=None, max=None): """ Parameters ---------- min : `~astropy.units.Quantity` or `None` (optional) Minimum acceptable Galactic latitude of target (inclusive). `None` indicates no limit. max : `~astropy.units.Quantity` or `None` (optional) Minimum acceptable Galactic latitude of target (inclusive). `None` indicates no limit. """ self.min = min self.max = max def compute_constraint(self, times, observer, targets): separation = abs(targets.transform_to(Galactic).b) if self.min is None and self.max is not None: mask = self.max >= separation elif self.max is None and self.min is not None: mask = self.min <= separation elif self.min is not None and self.max is not None: mask = ((self.min <= separation) & (separation <= self.max)) else: raise ValueError("No max and/or min specified in " "GalacticLatitudeConstraint.") return mask class SunSeparationConstraint(Constraint): """ Constrain the distance between the Sun and some targets. """ def __init__(self, min=None, max=None): """ Parameters ---------- min : `~astropy.units.Quantity` or `None` (optional) Minimum acceptable separation between Sun and target (inclusive). `None` indicates no limit. max : `~astropy.units.Quantity` or `None` (optional) Maximum acceptable separation between Sun and target (inclusive). `None` indicates no limit. """ self.min = min self.max = max def compute_constraint(self, times, observer, targets): # use get_body rather than get sun here, since # it returns the Sun's coordinates in an observer # centred frame, so the separation is as-seen # by the observer. # 'get_sun' returns ICRS coords. sun = get_body('sun', times, location=observer.location) targets = get_skycoord(targets) solar_separation = sun.separation(targets) if self.min is None and self.max is not None: mask = self.max >= solar_separation elif self.max is None and self.min is not None: mask = self.min <= solar_separation elif self.min is not None and self.max is not None: mask = ((self.min <= solar_separation) & (solar_separation <= self.max)) else: raise ValueError("No max and/or min specified in " "SunSeparationConstraint.") return mask class MoonSeparationConstraint(Constraint): """ Constrain the distance between the Earth's moon and some targets. """ def __init__(self, min=None, max=None, ephemeris=None): """ Parameters ---------- min : `~astropy.units.Quantity` or `None` (optional) Minimum acceptable separation between moon and target (inclusive). `None` indicates no limit. max : `~astropy.units.Quantity` or `None` (optional) Maximum acceptable separation between moon and target (inclusive). `None` indicates no limit. ephemeris : str, optional Ephemeris to use. If not given, use the one set with ``astropy.coordinates.solar_system_ephemeris.set`` (which is set to 'builtin' by default). """ self.min = min self.max = max self.ephemeris = ephemeris def compute_constraint(self, times, observer, targets): moon = get_body("moon", times, location=observer.location, ephemeris=self.ephemeris) # note to future editors - the order matters here # moon.separation(targets) is NOT the same as targets.separation(moon) # the former calculates the separation in the frame of the moon coord # which is GCRS, and that is what we want. targets = get_skycoord(targets) moon_separation = moon.separation(targets) if self.min is None and self.max is not None: mask = self.max >= moon_separation elif self.max is None and self.min is not None: mask = self.min <= moon_separation elif self.min is not None and self.max is not None: mask = ((self.min <= moon_separation) & (moon_separation <= self.max)) else: raise ValueError("No max and/or min specified in " "MoonSeparationConstraint.") return mask class MoonIlluminationConstraint(Constraint): """ Constrain the fractional illumination of the Earth's moon. Constraint is also satisfied if the Moon has set. """ def __init__(self, min=None, max=None, ephemeris=None): """ Parameters ---------- min : float or `None` (optional) Minimum acceptable fractional illumination (inclusive). `None` indicates no limit. max : float or `None` (optional) Maximum acceptable fractional illumination (inclusive). `None` indicates no limit. ephemeris : str, optional Ephemeris to use. If not given, use the one set with `~astropy.coordinates.solar_system_ephemeris` (which is set to 'builtin' by default). """ self.min = min self.max = max self.ephemeris = ephemeris @classmethod def dark(cls, min=None, max=0.25, **kwargs): """ initialize a `~astroplan.constraints.MoonIlluminationConstraint` with defaults of no minimum and a maximum of 0.25 Parameters ---------- min : float or `None` (optional) Minimum acceptable fractional illumination (inclusive). `None` indicates no limit. max : float or `None` (optional) Maximum acceptable fractional illumination (inclusive). `None` indicates no limit. """ return cls(min, max, **kwargs) @classmethod def grey(cls, min=0.25, max=0.65, **kwargs): """ initialize a `~astroplan.constraints.MoonIlluminationConstraint` with defaults of a minimum of 0.25 and a maximum of 0.65 Parameters ---------- min : float or `None` (optional) Minimum acceptable fractional illumination (inclusive). `None` indicates no limit. max : float or `None` (optional) Maximum acceptable fractional illumination (inclusive). `None` indicates no limit. """ return cls(min, max, **kwargs) @classmethod def bright(cls, min=0.65, max=None, **kwargs): """ initialize a `~astroplan.constraints.MoonIlluminationConstraint` with defaults of a minimum of 0.65 and no maximum Parameters ---------- min : float or `None` (optional) Minimum acceptable fractional illumination (inclusive). `None` indicates no limit. max : float or `None` (optional) Maximum acceptable fractional illumination (inclusive). `None` indicates no limit. """ return cls(min, max, **kwargs) def compute_constraint(self, times, observer, targets): # first is the moon up? cached_moon = _get_moon_data(times, observer) moon_alt = cached_moon['altaz'].alt moon_down_mask = moon_alt < 0 moon_up_mask = moon_alt >= 0 illumination = cached_moon['illum'] if self.min is None and self.max is not None: mask = (self.max >= illumination) | moon_down_mask elif self.max is None and self.min is not None: mask = (self.min <= illumination) & moon_up_mask elif self.min is not None and self.max is not None: mask = ((self.min <= illumination) & (illumination <= self.max)) & moon_up_mask else: raise ValueError("No max and/or min specified in " "MoonSeparationConstraint.") return mask class LocalTimeConstraint(Constraint): """ Constrain the observable hours. """ def __init__(self, min=None, max=None): """ Parameters ---------- min : `~datetime.time` Earliest local time (inclusive). `None` indicates no limit. max : `~datetime.time` Latest local time (inclusive). `None` indicates no limit. Examples -------- Constrain the observations to targets that are observable between 23:50 and 04:08 local time: >>> from astroplan import Observer >>> from astroplan.constraints import LocalTimeConstraint >>> import datetime as dt >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii") >>> # bound times between 23:50 and 04:08 local Hawaiian time >>> constraint = LocalTimeConstraint(min=dt.time(23,50), max=dt.time(4,8)) """ self.min = min self.max = max if self.min is None and self.max is None: raise ValueError("You must at least supply either a minimum or a maximum time.") if self.min is not None: if not isinstance(self.min, datetime.time): raise TypeError("Time limits must be specified as datetime.time objects.") if self.max is not None: if not isinstance(self.max, datetime.time): raise TypeError("Time limits must be specified as datetime.time objects.") def compute_constraint(self, times, observer, targets): timezone = None # get timezone from time objects, or from observer if self.min is not None: timezone = self.min.tzinfo elif self.max is not None: timezone = self.max.tzinfo if timezone is None: timezone = observer.timezone if self.min is not None: min_time = self.min else: min_time = self.min = datetime.time(0, 0, 0) if self.max is not None: max_time = self.max else: max_time = datetime.time(23, 59, 59) # If time limits occur on same day: if min_time < max_time: try: mask = np.array([min_time <= t.time() <= max_time for t in times.datetime]) except BaseException: # use np.bool so shape queries don't cause problems mask = np.bool_(min_time <= times.datetime.time() <= max_time) # If time boundaries straddle midnight: else: try: mask = np.array([(t.time() >= min_time) or (t.time() <= max_time) for t in times.datetime]) except BaseException: mask = np.bool_((times.datetime.time() >= min_time) or (times.datetime.time() <= max_time)) return mask class TimeConstraint(Constraint): """Constrain the observing time to be within certain time limits. An example use case for this class would be to associate an acceptable time range with a specific observing block. This can be useful if not all observing blocks are valid over the time limits used in calls to `is_observable` or `is_always_observable`. """ def __init__(self, min=None, max=None): """ Parameters ---------- min : `~astropy.time.Time` Earliest time (inclusive). `None` indicates no limit. max : `~astropy.time.Time` Latest time (inclusive). `None` indicates no limit. Examples -------- Constrain the observations to targets that are observable between 2016-03-28 and 2016-03-30: >>> from astroplan import Observer >>> from astropy.time import Time >>> subaru = Observer.at_site("Subaru") >>> t1 = Time("2016-03-28T12:00:00") >>> t2 = Time("2016-03-30T12:00:00") >>> constraint = TimeConstraint(t1,t2) """ self.min = min self.max = max if self.min is None and self.max is None: raise ValueError("You must at least supply either a minimum or a " "maximum time.") if self.min is not None: if not isinstance(self.min, Time): raise TypeError("Time limits must be specified as " "astropy.time.Time objects.") if self.max is not None: if not isinstance(self.max, Time): raise TypeError("Time limits must be specified as " "astropy.time.Time objects.") def compute_constraint(self, times, observer, targets): with warnings.catch_warnings(): warnings.simplefilter('ignore') min_time = Time("1950-01-01T00:00:00") if self.min is None else self.min max_time = Time("2120-01-01T00:00:00") if self.max is None else self.max mask = np.logical_and(times > min_time, times < max_time) return mask class PrimaryEclipseConstraint(Constraint): """ Constrain observations to times during primary eclipse. """ def __init__(self, eclipsing_system): """ Parameters ---------- eclipsing_system : `~astroplan.periodic.EclipsingSystem` System which must be in primary eclipse. """ self.eclipsing_system = eclipsing_system def compute_constraint(self, times, observer=None, targets=None): mask = self.eclipsing_system.in_primary_eclipse(times) return mask class SecondaryEclipseConstraint(Constraint): """ Constrain observations to times during secondary eclipse. """ def __init__(self, eclipsing_system): """ Parameters ---------- eclipsing_system : `~astroplan.periodic.EclipsingSystem` System which must be in secondary eclipse. """ self.eclipsing_system = eclipsing_system def compute_constraint(self, times, observer=None, targets=None): mask = self.eclipsing_system.in_secondary_eclipse(times) return mask class PhaseConstraint(Constraint): """ Constrain observations to times in some range of phases for a periodic event (e.g.~transiting exoplanets, eclipsing binaries). """ def __init__(self, periodic_event, min=None, max=None): """ Parameters ---------- periodic_event : `~astroplan.periodic.PeriodicEvent` or subclass System on which to compute the phase. For example, the system could be an eclipsing or non-eclipsing binary, or exoplanet system. min : float (optional) Minimum phase (inclusive) on interval [0, 1). Default is zero. max : float (optional) Maximum phase (inclusive) on interval [0, 1). Default is one. Examples -------- To constrain observations on orbital phases between 0.4 and 0.6, >>> from astroplan import PeriodicEvent >>> from astropy.time import Time >>> import astropy.units as u >>> binary = PeriodicEvent(epoch=Time('2017-01-01 02:00'), period=1*u.day) >>> constraint = PhaseConstraint(binary, min=0.4, max=0.6) The minimum and maximum phase must be described on the interval [0, 1). To constrain observations on orbital phases between 0.6 and 1.2, for example, you should subtract one from the second number: >>> constraint = PhaseConstraint(binary, min=0.6, max=0.2) """ self.periodic_event = periodic_event if (min < 0) or (min > 1) or (max < 0) or (max > 1): raise ValueError('The minimum of the PhaseConstraint must be within' ' the interval [0, 1).') self.min = min if min is not None else 0.0 self.max = max if max is not None else 1.0 def compute_constraint(self, times, observer=None, targets=None): phase = self.periodic_event.phase(times) mask = np.where(self.max > self.min, (phase >= self.min) & (phase <= self.max), (phase >= self.min) | (phase <= self.max)) return mask def is_always_observable(constraints, observer, targets, times=None, time_range=None, time_grid_resolution=0.5*u.hour): """ A function to determine whether ``targets`` are always observable throughout ``time_range`` given constraints in the ``constraints_list`` for a particular ``observer``. Parameters ---------- constraints : list or `~astroplan.constraints.Constraint` Observational constraint(s) observer : `~astroplan.Observer` The observer who has constraints ``constraints`` targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets times : `~astropy.time.Time` (optional) Array of times on which to test the constraint time_range : `~astropy.time.Time` (optional) Lower and upper bounds on time sequence, with spacing ``time_resolution``. This will be passed as the first argument into `~astroplan.time_grid_from_range`. time_grid_resolution : `~astropy.units.Quantity` (optional) If ``time_range`` is specified, determine whether constraints are met between test times in ``time_range`` by checking constraint at linearly-spaced times separated by ``time_resolution``. Default is 0.5 hours. Returns ------- ever_observable : list List of booleans of same length as ``targets`` for whether or not each target is observable in the time range given the constraints. """ if not hasattr(constraints, '__len__'): constraints = [constraints] applied_constraints = [constraint(observer, targets, times=times, time_range=time_range, time_grid_resolution=time_grid_resolution, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and.reduce(applied_constraints) return np.all(constraint_arr, axis=1) def is_observable(constraints, observer, targets, times=None, time_range=None, time_grid_resolution=0.5*u.hour): """ Determines if the ``targets`` are observable during ``time_range`` given constraints in ``constraints_list`` for a particular ``observer``. Parameters ---------- constraints : list or `~astroplan.constraints.Constraint` Observational constraint(s) observer : `~astroplan.Observer` The observer who has constraints ``constraints`` targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets times : `~astropy.time.Time` (optional) Array of times on which to test the constraint time_range : `~astropy.time.Time` (optional) Lower and upper bounds on time sequence, with spacing ``time_resolution``. This will be passed as the first argument into `~astroplan.time_grid_from_range`. time_grid_resolution : `~astropy.units.Quantity` (optional) If ``time_range`` is specified, determine whether constraints are met between test times in ``time_range`` by checking constraint at linearly-spaced times separated by ``time_resolution``. Default is 0.5 hours. Returns ------- ever_observable : list List of booleans of same length as ``targets`` for whether or not each target is ever observable in the time range given the constraints. """ if not hasattr(constraints, '__len__'): constraints = [constraints] applied_constraints = [constraint(observer, targets, times=times, time_range=time_range, time_grid_resolution=time_grid_resolution, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and.reduce(applied_constraints) return np.any(constraint_arr, axis=1) def is_event_observable(constraints, observer, target, times=None, times_ingress_egress=None): """ Determines if the ``target`` is observable at each time in ``times``, given constraints in ``constraints`` for a particular ``observer``. Parameters ---------- constraints : list or `~astroplan.constraints.Constraint` Observational constraint(s) observer : `~astroplan.Observer` The observer who has constraints ``constraints`` target : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target times : `~astropy.time.Time` (optional) Array of mid-event times on which to test the constraints times_ingress_egress : `~astropy.time.Time` (optional) Array of ingress and egress times for ``N`` events, with shape (``N``, 2). Returns ------- event_observable : `~numpy.ndarray` Array of booleans of same length as ``times`` for whether or not the target is ever observable at each time, given the constraints. """ if not hasattr(constraints, '__len__'): constraints = [constraints] if times is not None: applied_constraints = [constraint(observer, target, times=times, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and.reduce(applied_constraints) else: times_ing = times_ingress_egress[:, 0] times_egr = times_ingress_egress[:, 1] applied_constraints_ing = [constraint(observer, target, times=times_ing, grid_times_targets=True) for constraint in constraints] applied_constraints_egr = [constraint(observer, target, times=times_egr, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and(np.logical_and.reduce(applied_constraints_ing), np.logical_and.reduce(applied_constraints_egr)) return constraint_arr def months_observable(constraints, observer, targets, time_range=_current_year_time_range, time_grid_resolution=0.5*u.hour): """ Determines which month the specified ``targets`` are observable for a specific ``observer``, given the supplied ``constraints``. Parameters ---------- constraints : list or `~astroplan.constraints.Constraint` Observational constraint(s) observer : `~astroplan.Observer` The observer who has constraints ``constraints`` targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets time_range : `~astropy.time.Time` (optional) Lower and upper bounds on time sequence If ``time_range`` is not specified, defaults to current year (localtime) time_grid_resolution : `~astropy.units.Quantity` (optional) If ``time_range`` is specified, determine whether constraints are met between test times in ``time_range`` by checking constraint at linearly-spaced times separated by ``time_resolution``. Default is 0.5 hours. Returns ------- observable_months : list List of sets of unique integers representing each month that a target is observable, one set per target. These integers are 1-based so that January maps to 1, February maps to 2, etc. """ # TODO: This method could be sped up a lot by dropping to the trigonometric # altitude calculations. if not hasattr(constraints, '__len__'): constraints = [constraints] times = time_grid_from_range(time_range, time_grid_resolution) # If the constraints don't include AltitudeConstraint or its subclasses, # warn the user that they may get months when the target is below the horizon altitude_constraint_supplied = any( [isinstance(constraint, AltitudeConstraint) for constraint in constraints] ) if not altitude_constraint_supplied: message = ("months_observable usually expects an AltitudeConstraint or " "AirmassConstraint to ensure targets are above horizon.") warnings.warn(message, MissingConstraintWarning) # TODO: This method could be sped up a lot by dropping to the trigonometric # altitude calculations. applied_constraints = [constraint(observer, targets, times=times, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and.reduce(applied_constraints) months_observable = [] for target, observable in zip(targets, constraint_arr): s = set([t.datetime.month for t in times[observable]]) months_observable.append(s) return months_observable def observability_table(constraints, observer, targets, times=None, time_range=None, time_grid_resolution=0.5*u.hour): """ Creates a table with information about observability for all the ``targets`` over the requested ``time_range``, given the constraints in ``constraints_list`` for ``observer``. Parameters ---------- constraints : list or `~astroplan.constraints.Constraint` Observational constraint(s) observer : `~astroplan.Observer` The observer who has constraints ``constraints`` targets : {list, `~astropy.coordinates.SkyCoord`, `~astroplan.FixedTarget`} Target or list of targets times : `~astropy.time.Time` (optional) Array of times on which to test the constraint time_range : `~astropy.time.Time` (optional) Lower and upper bounds on time sequence, with spacing ``time_resolution``. This will be passed as the first argument into `~astroplan.time_grid_from_range`. If a single (scalar) time, the table will be for a 24 hour period centered on that time. time_grid_resolution : `~astropy.units.Quantity` (optional) If ``time_range`` is specified, determine whether constraints are met between test times in ``time_range`` by checking constraint at linearly-spaced times separated by ``time_resolution``. Default is 0.5 hours. Returns ------- observability_table : `~astropy.table.Table` A Table containing the observability information for each of the ``targets``. The table contains four columns with information about the target and it's observability: ``'target name'``, ``'ever observable'``, ``'always observable'``, and ``'fraction of time observable'``. The column ``'time observable'`` will also be present if the ``time_range`` is given as a scalar. It also contains metadata entries ``'times'`` (with an array of all the times), ``'observer'`` (the `~astroplan.Observer` object), and ``'constraints'`` (containing the supplied ``constraints``). """ if not hasattr(constraints, '__len__'): constraints = [constraints] is_24hr_table = False if hasattr(time_range, 'isscalar') and time_range.isscalar: time_range = (time_range-12*u.hour, time_range+12*u.hour) is_24hr_table = True applied_constraints = [constraint(observer, targets, times=times, time_range=time_range, time_grid_resolution=time_grid_resolution, grid_times_targets=True) for constraint in constraints] constraint_arr = np.logical_and.reduce(applied_constraints) colnames = ['target name', 'ever observable', 'always observable', 'fraction of time observable'] target_names = [target.name for target in targets] ever_obs = np.any(constraint_arr, axis=1) always_obs = np.all(constraint_arr, axis=1) frac_obs = np.sum(constraint_arr, axis=1) / constraint_arr.shape[1] tab = table.Table(names=colnames, data=[target_names, ever_obs, always_obs, frac_obs]) if times is None and time_range is not None: times = time_grid_from_range(time_range, time_resolution=time_grid_resolution) if is_24hr_table: tab['time observable'] = tab['fraction of time observable'] * 24*u.hour tab.meta['times'] = times.datetime tab.meta['observer'] = observer tab.meta['constraints'] = constraints return tab def min_best_rescale(vals, min_val, max_val, less_than_min=1): """ rescales an input array ``vals`` to be a score (between zero and one), where the ``min_val`` goes to one, and the ``max_val`` goes to zero. Parameters ---------- vals : array-like the values that need to be rescaled to be between 0 and 1 min_val : float worst acceptable value (rescales to 0) max_val : float best value cared about (rescales to 1) less_than_min : 0 or 1 what is returned for ``vals`` below ``min_val``. (in some cases anything less than ``min_val`` should also return one, in some cases it should return zero) Returns ------- array of floats between 0 and 1 inclusive rescaled so that ``vals`` equal to ``max_val`` equal 0 and those equal to ``min_val`` equal 1 Examples -------- rescale airmasses to between 0 and 1, with the best (1) and worst (2.25). All values outside the range should return 0. >>> from astroplan.constraints import min_best_rescale >>> import numpy as np >>> airmasses = np.array([1, 1.5, 2, 3, 0]) >>> min_best_rescale(airmasses, 1, 2.25, less_than_min = 0) # doctest: +FLOAT_CMP array([ 1. , 0.6, 0.2, 0. , 0. ]) """ rescaled = (vals - max_val) / (min_val - max_val) below = vals < min_val above = vals > max_val rescaled[below] = less_than_min rescaled[above] = 0 return rescaled def max_best_rescale(vals, min_val, max_val, greater_than_max=1): """ rescales an input array ``vals`` to be a score (between zero and one), where the ``max_val`` goes to one, and the ``min_val`` goes to zero. Parameters ---------- vals : array-like the values that need to be rescaled to be between 0 and 1 min_val : float worst acceptable value (rescales to 0) max_val : float best value cared about (rescales to 1) greater_than_max : 0 or 1 what is returned for ``vals`` above ``max_val``. (in some cases anything higher than ``max_val`` should also return one, in some cases it should return zero) Returns ------- array of floats between 0 and 1 inclusive rescaled so that ``vals`` equal to ``min_val`` equal 0 and those equal to ``max_val`` equal 1 Examples -------- rescale an array of altitudes to be between 0 and 1, with the best (60) going to 1 and worst (35) going to 0. For values outside the range, the rescale should return 0 below 35 and 1 above 60. >>> from astroplan.constraints import max_best_rescale >>> import numpy as np >>> altitudes = np.array([20, 30, 40, 45, 55, 70]) >>> max_best_rescale(altitudes, 35, 60) # doctest: +FLOAT_CMP array([ 0. , 0. , 0.2, 0.4, 0.8, 1. ]) """ rescaled = (vals - min_val) / (max_val - min_val) below = vals < min_val above = vals > max_val rescaled[below] = 0 rescaled[above] = greater_than_max return rescaled ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1673375923.0 astroplan-0.9.1/astroplan/exceptions.py0000644001274200020070000000231614357330263021320 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst from __future__ import (absolute_import, division, print_function, unicode_literals) from astropy.utils.exceptions import AstropyWarning __all__ = ["TargetAlwaysUpWarning", "TargetNeverUpWarning", "OldEarthOrientationDataWarning", "PlotWarning", "PlotBelowHorizonWarning", "AstroplanWarning", "MissingConstraintWarning"] class AstroplanWarning(AstropyWarning): """Superclass for warnings used by astroplan""" class TargetAlwaysUpWarning(AstroplanWarning): """Target is circumpolar""" pass class TargetNeverUpWarning(AstroplanWarning): """Target never rises above horizon""" pass class OldEarthOrientationDataWarning(AstroplanWarning): """Using old Earth rotation data from IERS""" pass class PlotWarning(AstroplanWarning): """Warnings dealing with the plotting aspects of astroplan""" pass class PlotBelowHorizonWarning(PlotWarning): """Warning for when something is hidden on a plot because it's below the horizon""" pass class MissingConstraintWarning(AstroplanWarning): """Triggered when a constraint is expected but not supplied""" pass ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1690478983.0 astroplan-0.9.1/astroplan/moon.py0000644001274200020070000000334014460524607020107 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst """ This version of the `moon` module calculates lunar phase angle for a geocentric """ from __future__ import (absolute_import, division, print_function, unicode_literals) # Third-party import numpy as np from astropy.coordinates import get_sun, get_body __all__ = ["moon_phase_angle", "moon_illumination"] def moon_phase_angle(time, ephemeris=None): """ Calculate lunar orbital phase in radians. Parameters ---------- time : `~astropy.time.Time` Time of observation ephemeris : str, optional Ephemeris to use. If not given, use the one set with `~astropy.coordinates.solar_system_ephemeris` (which is set to 'builtin' by default). Returns ------- i : `~astropy.units.Quantity` Phase angle of the moon [radians] """ # TODO: cache these sun/moon SkyCoord objects sun = get_sun(time) moon = get_body("moon", time, ephemeris=ephemeris) elongation = sun.separation(moon) return np.arctan2(sun.distance*np.sin(elongation), moon.distance - sun.distance*np.cos(elongation)) def moon_illumination(time, ephemeris=None): """ Calculate fraction of the moon illuminated. Parameters ---------- time : `~astropy.time.Time` Time of observation ephemeris : str, optional Ephemeris to use. If not given, use the one set with `~astropy.coordinates.solar_system_ephemeris` (which is set to 'builtin' by default). Returns ------- k : float Fraction of moon illuminated """ i = moon_phase_angle(time, ephemeris=ephemeris) k = (1 + np.cos(i))/2.0 return k.value ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1690478983.0 astroplan-0.9.1/astroplan/observer.py0000644001274200020070000024006114460524607020771 0ustar00bmmorrisSTSCI\science# Licensed under a 3-clause BSD style license - see LICENSE.rst from __future__ import (absolute_import, division, print_function, unicode_literals) from six import string_types # Standard library import sys import datetime import warnings # Third-party from astropy.coordinates import (EarthLocation, SkyCoord, AltAz, get_sun, get_body, Angle, Longitude) import astropy.units as u from astropy.time import Time from astropy.utils.exceptions import AstropyDeprecationWarning import numpy as np import pytz # Package from .exceptions import TargetNeverUpWarning, TargetAlwaysUpWarning from .moon import moon_illumination, moon_phase_angle from .target import get_skycoord, SunFlag, MoonFlag __all__ = ["Observer"] MAGIC_TIME = Time(-999, format='jd') # Handle deprecated MAGIC_TIME variable def deprecation_wrap_module(mod, deprecated): """Return a wrapped object that warns about deprecated accesses""" deprecated = set(deprecated) class DeprecateWrapper(object): def __getattr__(self, attr): if attr in deprecated: warnmsg = ("`MAGIC_TIME` will be deprecated in future versions " "of astroplan. Use masked Time objects instead.") warnings.warn(warnmsg, AstropyDeprecationWarning) return getattr(mod, attr) return DeprecateWrapper() sys.modules[__name__] = deprecation_wrap_module(sys.modules[__name__], deprecated=['MAGIC_TIME']) def _process_nans_in_jds(jds): """ Some functions calculate times for events that won't happen, yielding nans. This wrapper manages vectors of (potentially) invalid JDs that must be passed to the astropy.time.Time constructor. Returns a masked Time object. """ if np.isscalar(jds): jds = np.array([jds]) not_finite = ~np.isfinite(jds) masked_jds = np.ma.masked_array(jds.to(u.day).value if hasattr(jds, 'unit') else jds.copy()) masked_jds[not_finite] = np.ma.masked return masked_jds def _generate_24hr_grid(t0, start, end, n_grid_points, for_deriv=False): """ Generate a nearly linearly spaced grid of time durations. The midpoints of these grid points will span times from ``t0``+``start`` to ``t0``+``end``, including the end points, which is useful when taking numerical derivatives. Parameters ---------- t0 : `~astropy.time.Time` Time queried for, grid will be built from or up to this time. start : float Number of days before/after ``t0`` to start the grid. end : float Number of days before/after ``t0`` to end the grid. n_grid_points : int (optional) Number of grid points to generate for_deriv : bool Generate time series for taking numerical derivative (modify bounds)? Returns ------- `~astropy.time.Time` """ if for_deriv: time_grid = np.concatenate([[start - 1 / (n_grid_points - 1)], np.linspace(start, end, n_grid_points)[1:-1], [end + 1 / (n_grid_points - 1)]]) * u.day else: time_grid = np.linspace(start, end, n_grid_points) * u.day # broadcast so grid is first index, and remaining shape of t0 # falls in later indices. e.g. if t0 is shape (10), time_grid # will be shape (N, 10). If t0 is shape (5, 2), time_grid is (N, 5, 2) while time_grid.ndim <= t0.ndim: time_grid = time_grid[:, np.newaxis] # we want to avoid 1D grids since we always want to broadcast against targets if time_grid.ndim == 1: time_grid = time_grid[:, np.newaxis] return t0 + time_grid class Observer(object): """ A container class for information about an observer's location and environment. Examples -------- We can create an observer at Subaru Observatory in Hawaii two ways. First, locations for some observatories are stored in astroplan, and these can be accessed by name, like so: >>> from astroplan import Observer >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii") To find out which observatories can be accessed by name, check out `~astropy.coordinates.EarthLocation.get_site_names`. Next, you can initialize an observer by specifying the location with `~astropy.coordinates.EarthLocation`: >>> from astropy.coordinates import EarthLocation >>> import astropy.units as u >>> location = EarthLocation.from_geodetic(-155.4761*u.deg, 19.825*u.deg, ... 4139*u.m) >>> subaru = Observer(location=location, name="Subaru", timezone="US/Hawaii") You can also create an observer without an `~astropy.coordinates.EarthLocation`: >>> from astroplan import Observer >>> import astropy.units as u >>> subaru = Observer(longitude=-155.4761*u.deg, latitude=19.825*u.deg, ... elevation=0*u.m, name="Subaru", timezone="US/Hawaii") """ @u.quantity_input(elevation=u.m) def __init__(self, location=None, timezone='UTC', name=None, latitude=None, longitude=None, elevation=0*u.m, pressure=None, relative_humidity=None, temperature=None, description=None): """ Parameters ---------- location : `~astropy.coordinates.EarthLocation` The location (latitude, longitude, elevation) of the observatory. timezone : str or `datetime.tzinfo` (optional) The local timezone to assume. If a string, it will be passed through ``pytz.timezone()`` to produce the timezone object. name : str A short name for the telescope, observatory or location. latitude : float, str, `~astropy.units.Quantity` (optional) The latitude of the observing location. Should be valid input for initializing a `~astropy.coordinates.Latitude` object. longitude : float, str, `~astropy.units.Quantity` (optional) The longitude of the observing location. Should be valid input for initializing a `~astropy.coordinates.Longitude` object. elevation : `~astropy.units.Quantity` (optional), default = 0 meters The elevation of the observing location, with respect to sea level. Defaults to sea level. pressure : `~astropy.units.Quantity` (optional) The ambient pressure. Defaults to zero (i.e. no atmosphere). relative_humidity : float (optional) The ambient relative humidity. temperature : `~astropy.units.Quantity` (optional) The ambient temperature. description : str (optional) A short description of the telescope, observatory or observing location. """ self.name = name self.pressure = pressure self.temperature = temperature self.relative_humidity = relative_humidity # If lat/long given instead of EarthLocation, convert them # to EarthLocation if location is None and (latitude is not None and longitude is not None): self.location = EarthLocation.from_geodetic(longitude, latitude, elevation) elif isinstance(location, EarthLocation): self.location = location else: raise TypeError('Observatory location must be specified with ' 'either (1) an instance of ' 'astropy.coordinates.EarthLocation or (2) ' 'latitude and longitude in degrees as ' 'accepted by astropy.coordinates.Latitude and ' 'astropy.coordinates.Latitude.') # Accept various timezone inputs, default to UTC if isinstance(timezone, datetime.tzinfo): self.timezone = timezone elif isinstance(timezone, string_types): self.timezone = pytz.timezone(timezone) else: raise TypeError('timezone keyword should be a string, or an ' 'instance of datetime.tzinfo') @property def longitude(self): """The longitude of the observing location, derived from the location.""" return self.location.lon @property def latitude(self): """The latitude of the observing location, derived from the location.""" return self.location.lat @property def elevation(self): """The elevation of the observing location with respect to sea level.""" return self.location.height def __repr__(self): """ String representation of the `~astroplan.Observer` object. Examples -------- >>> from astroplan import Observer >>> keck = Observer.at_site("Keck", timezone="US/Hawaii") >>> print(keck) # doctest: +FLOAT_CMP > """ class_name = self.__class__.__name__ attr_names = ['name', 'location', 'timezone', 'pressure', 'temperature', 'relative_humidity'] attr_values = [getattr(self, attr) for attr in attr_names] attributes_strings = [] for name, value in zip(attr_names, attr_values): if value is not None: # Format location for easy readability if name == 'location': formatted_loc = ["{} {}".format(i.value, i.unit) for i in value.to_geodetic()] attributes_strings.append( "{} (lon, lat, el)=({})".format( name, ", ".join(formatted_loc))) else: if name != 'name': value = repr(value) else: value = "'{}'".format(value) attributes_strings.append("{}={}".format(name, value)) return "<{}: {}>".format(class_name, ",\n ".join(attributes_strings)) def _key(self): """ Generate a tuple of the attributes that determine uniqueness of `~astroplan.Observer` objects. Returns ------- key : tuple Examples -------- >>> from astroplan import Observer >>> keck = Observer.at_site("Keck", timezone="US/Hawaii") >>> keck._key() ('Keck', None, None, None, , , , ) """ return (self.name, self.pressure, self.temperature, self.relative_humidity, self.longitude, self.latitude, self.elevation, self.timezone,) def __hash__(self): """ Hash the `~astroplan.Observer` object. Examples -------- >>> from astroplan import Observer >>> keck = Observer.at_site("Keck", timezone="US/Hawaii") >>> hash(keck) -3872382927731250571 """ return hash(self._key()) def __eq__(self, other): """ Equality check for `~astroplan.Observer` objects. Examples -------- >>> from astroplan import Observer >>> keck = Observer.at_site("Keck", timezone="US/Hawaii") >>> keck2 = Observer.at_site("Keck", timezone="US/Hawaii") >>> keck == keck2 True """ if isinstance(other, Observer): return self._key() == other._key() else: return NotImplemented def __ne__(self, other): """ Inequality check for `~astroplan.Observer` objects. Examples -------- >>> from astroplan import Observer >>> keck = Observer.at_site("Keck", timezone="US/Hawaii") >>> kpno = Observer.at_site("KPNO", timezone="US/Arizona") >>> keck != kpno True """ return not self.__eq__(other) @classmethod def at_site(cls, site_name, **kwargs): """ Initialize an `~astroplan.observer.Observer` object with a site name. Extra keyword arguments are passed to the `~astroplan.Observer` constructor (see `~astroplan.Observer` for available keyword arguments). Parameters ---------- site_name : str Observatory name, must be resolvable with `~astropy.coordinates.EarthLocation.get_site_names`. Returns ------- `~astroplan.observer.Observer` Observer object. Examples -------- Initialize an observer at Kitt Peak National Observatory: >>> from astroplan import Observer >>> import astropy.units as u >>> kpno_generic = Observer.at_site('kpno') >>> kpno_today = Observer.at_site('kpno', pressure=1*u.bar, temperature=0*u.deg_C) """ name = kwargs.pop('name', site_name) if 'location' in kwargs: raise ValueError("Location kwarg should not be used if " "initializing an Observer with Observer.at_site()") return cls(location=EarthLocation.of_site(site_name), name=name, **kwargs) def astropy_time_to_datetime(self, astropy_time): """ Convert the `~astropy.time.Time` object ``astropy_time`` to a localized `~datetime.datetime` object. Timezones localized with `pytz`_. .. _pytz: https://pypi.python.org/pypi/pytz/ Parameters ---------- astropy_time : `~astropy.time.Time` Scalar or list-like. Returns ------- `~datetime.datetime` Localized datetime, where the timezone of the datetime is set by the ``timezone`` keyword argument of the `~astroplan.Observer` constructor. Examples -------- Convert an astropy time to a localized `~datetime.datetime`: >>> from astroplan import Observer >>> from astropy.time import Time >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii") >>> astropy_time = Time('1999-12-31 06:00:00') >>> print(subaru.astropy_time_to_datetime(astropy_time)) 1999-12-30 20:00:00-10:00 """ if not astropy_time.isscalar: return [self.astropy_time_to_datetime(t) for t in astropy_time] # Convert astropy.time.Time to a UTC localized datetime (aware) utc_datetime = pytz.utc.localize(astropy_time.utc.datetime) # Convert UTC to local timezone return self.timezone.normalize(utc_datetime) def datetime_to_astropy_time(self, date_time): """ Convert the `~datetime.datetime` object ``date_time`` to a `~astropy.time.Time` object. Timezones localized with `pytz`_. If the ``date_time`` is naive, the implied timezone is the ``timezone`` structure of ``self``. Parameters ---------- date_time : `~datetime.datetime` or list-like Returns ------- `~astropy.time.Time` Astropy time object (no timezone information preserved). Examples -------- Convert a localized `~datetime.datetime` to a `~astropy.time.Time` object. Non-localized datetimes are assumed to be UTC.