Metadata-Version: 2.1
Name: tilepy
Version: 3.0.2
Summary: Computation of the tiling scheduling of large localization uncertainty region event with multi-wavelength pointing telescopes.
Author-email: "Monica Seglar-Arroyo, Halim Ashkar, Fabian Schussler, Mathieu de Bony" <astro.tilepy@gmail.com>
Maintainer-email: Monica Seglar-Arroyo <mosear2@gmail.com>, Halim Ashkar <halim.ashkar@llr.in2p3.fr>, Fabian Schussler <fabian.schussler@cea.fr>, Mathieu de Bony <mathieu.debony@cea.fr>
License: ************************************************************************
        GNU LESSER GENERAL PUBLIC LICENSE
        Version 3, 29 June 2007
        ************************************************************************
        
        Copyright (C) 2007 Free Software Foundation, Inc.
        <http://fsf.org/>
        
        Everyone is permitted to copy and distribute verbatim copies of this license
        document, but changing it is not allowed.
        
        .. contents::
        
        Preamble
        ========
        
        The GNU Lesser General Public License is a free, copyleft license for software
        and other kinds of works, specifically designed to allow linking with
        proprietary software under certain conditions.
        
        The licenses for most software and other practical works are designed to take
        away your freedom to share and change the works. By contrast, the GNU Lesser
        General Public License is intended to guarantee your freedom to share and change
        all versions of a program—ensuring it remains free software for all its users.
        
        When we speak of free software, we are referring to freedom, not price.
        Our General Public Licenses are designed to ensure you have the freedom to
        distribute copies of free software, receive source code, modify it, and know you
        can do these things.
        
        The precise terms and conditions for copying, distribution and modification follow.
        
        Terms and Conditions
        ===================
        
        0. Definitions
        --------------
        
        - "This License" refers to version 3 of the GNU Lesser General Public License.
        - "Copyright" also means copyright-like laws applying to other works.
        - "The Library" refers to the software covered by this License.
        - "You" refers to any licensee of the Library.
        
        1. Source Code
        --------------
        
        - "Source code" means the preferred form of the work for making modifications.
        - "Object code" means any non-source form of a work.
        - "Corresponding Source" means all source code needed to build, install, and run the object code.
        
        2. Basic Permissions
        --------------------
        
        You may run, modify, and propagate covered works under the terms of this License,
        subject to the conditions described herein.
        
        3. Protecting Users' Legal Rights
        ---------------------------------
        
        You may not use technical measures to deny others the rights granted by this License.
        
        4. Conveying Verbatim Copies
        ----------------------------
        
        You may convey verbatim copies of the Library in any medium, provided that you
        keep intact all notices and give recipients a copy of this License.
        
        5. Conveying Modified Versions
        ------------------------------
        
        You may convey a modified version of the Library, provided that you:
        
        - a) Include prominent notices stating you changed it.
        - b) License the entire work under this License.
        - c) Include the Corresponding Source or a written offer to provide it.
        
        6. Conveying Non-Source Forms
        -----------------------------
        
        - You may distribute object code forms provided you make the Corresponding Source
        available in one of the approved ways described in the License.
        
        7. Additional Terms
        -------------------
        
        - You may supplement the terms with disclaimers, attribution, or patent grants,
        as long as they comply with LGPL requirements.
        
        8. Termination
        --------------
        
        - Violating the License automatically terminates your rights.
        - Rights may be reinstated if violations cease within the conditions described.
        
        9. Acceptance Not Required for Having Copies
        --------------------------------------------
        
        - You are not required to accept the License just to receive or run a copy of the Library.
        
        10. Automatic Licensing of Downstream Recipients
        ------------------------------------------------
        
        - Recipients automatically receive a license to exercise rights under this License.
        
        11. Patents
        -----------
        
        - Contributors grant a non-exclusive, worldwide, royalty-free patent license to
        use, modify, and propagate the Library.
        
        12. No Surrender of Others' Freedom
        -----------------------------------
        
        - You cannot impose additional restrictions that contradict this License.
        
        13. Revised Versions of this License
        -----------------------------------
        
        - The Free Software Foundation may publish revised versions of the LGPL.
        - You may follow the terms of the version specified or any later version.
        
        14. Disclaimer of Warranty
        -------------------------
        
        - The Library is provided "as is," without warranty of any kind.
        
        15. Limitation of Liability
        ---------------------------
        
        - The authors or copyright holders are not liable for any damages arising from
          the use of the Library.
        
        ---
        
        How to Apply These Terms to Tilepy
        ==================================
        
        If you develop a new program and want it to be useful to the public, attach the
        following notice to your files:
        
        ::
        
            Tilepy
            Copyright (C) 2016-2025 Tilepy developers
            (Monica Seglar-Arroyo, Halim Ashkar, Fabian Schussler, Mathieu de Bony)
        
            This program is free software: you can redistribute it and/or modify
            it under the terms of the GNU Lesser General Public License as published
            by the Free Software Foundation, either version 3 of the License, or
            (at your option) any later version.
        
            This program is distributed in the hope that it will be useful,
            but WITHOUT ANY WARRANTY; without even the implied warranty of
            MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
            See the GNU Lesser General Public License for more details.
        
            You should have received a copy of the GNU Lesser General Public License
            along with this program. If not, see <http://www.gnu.org/licenses/>.
        
Project-URL: repository, https://github.com/astro-transients/tilepy
Project-URL: documentation, https://github.com/astro-transients/tilepy
Project-URL: Homepage, https://tilepy.readthedocs.io/
Project-URL: Bug Tracker, https://github.com/astro-transients/tilepy/issues
Project-URL: Documentation, https://tilepy.readthedocs.io/
Project-URL: GitHub, https://github.com/astro-transients/tilepy
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.rst
Requires-Dist: astropy
Requires-Dist: scipy<1.14.0
Requires-Dist: numpy
Requires-Dist: healpy==1.16.2
Requires-Dist: ipython
Requires-Dist: matplotlib<3.9.0
Requires-Dist: MOCpy
Requires-Dist: pandas
Requires-Dist: pytz
Requires-Dist: ephem
Requires-Dist: gdpyc
Requires-Dist: tables
Requires-Dist: fastparquet
Requires-Dist: skyfield
Requires-Dist: mhealpy<0.4,>=0.3.0
Requires-Dist: ligo.skymap>=2.0.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: setuptools<71,>=64
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-doctestplus; extra == "tests"
Requires-Dist: tomli; extra == "tests"
Requires-Dist: nbmake>=1.5.5; extra == "tests"
Provides-Extra: docs
Requires-Dist: numpy<2; extra == "docs"
Requires-Dist: python-ligo-lw; extra == "docs"
Requires-Dist: sphinx>=1.6; extra == "docs"
Requires-Dist: sphinx-astropy[confv2]; extra == "docs"
Requires-Dist: sphinxcontrib-typer; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: astropy-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: setuptools<71,>=64; extra == "docs"
Provides-Extra: dev
Requires-Dist: setuptools_scm[toml]; extra == "dev"
Requires-Dist: pre-commit>=4.1.0; extra == "dev"
Requires-Dist: flake8>=7.1.2; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: sphinxcontrib-bibtex; extra == "dev"
Requires-Dist: pytest-astropy; extra == "dev"
Provides-Extra: all
Requires-Dist: tilepy[dev,tests]; extra == "all"

<p align="center">
  <a href="" rel="noopener">
    <img style="width: 400px; height: 200px; max-width: 100%;" src="image/tilepy_logo.png" alt="tilepy logo">
  </a>
</p>

<div align="center">


[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12190543.svg)](https://doi.org/10.5281/zenodo.12190543)
[![Latest release](http://img.shields.io/pypi/v/tilepy.svg?text=version)](https://pypi.org/project/tilepy/)
[![License: LGPL v3](https://img.shields.io/badge/License-LGPLv3-blue.svg)](https://github.com/astro-transients/tilepy/blob/master/LICENSE.rst)
[![CLA assistant](https://cla-assistant.io/readme/badge/astro-transients/tilepy)](https://cla-assistant.io/astro-transients/tilepy)
[![ApJS Published](https://img.shields.io/badge/ApJS-Published-Green.svg)](https://doi.org/10.3847/1538-4365/ad5bde)
[![Documentation Status](https://readthedocs.org/projects/tilepy/badge/?version=latest)](https://tilepy.readthedocs.io/en/latest)


</div>

## Installation

We clone the repo, create an environment to work, activate the environment and install the package. You can use conda or mamba for this.

```python
git clone git@github.com:astro-transients/tilepy.git
cd tilepy
conda env create -n tilepyenv -f environment.yml
conda activate tilepyenv
python -m pip install .
```
Some users have encounter problems with the use of the `mocpy` package within conda. If this is your case follow these instructions:
```python
- remove mocpy from the environment.yml
- create and activate the environment as described above
- run "pip install mocpy"
```

If you prefer to avoid conda and use a virtual environment with your favorite python version, use the following sequence:
```
python -m venv tilepy_venv
source tilepy_venv/bin/activate
pip3 install --upgrade pip
python -m pip install -r requirements.txt
```

Requirements of the installation:

- The current version of the package **only** runs with `python>=3.9`. Python 3.9 is recommended. Be careful as well with the versions of matplotlib and healpy, they should be the ones explicitly given in the requirements.yml, otherwise conflicts between them when plotting skymaps will arise.
- Note that by creating the env from the environment.yml, the libraries and versions needed will be installed automatically.
- Note that every time we made changes to the package, you should update the installation of the package doing ```pip install .``` in the folder where the setup.py is located. The changes will be only applied to the env in which you are working.
- The package relies on 'curl' to download the localisation map of the multi-messenger events.

In the case you are working in CC-Lyon, the easiest solution is to do```ccenv conda ``` and then follow the instructions given above.

If you have any problem with the installation of the package, please drop an email to `astro.tilepy@gmail.com` or join the discussion forum at `https://forum.astro-colibri.science/c/instrumentation-and-tools/tilepy`

## Creation of a galaxy catalog

For using the 3D algorithm tilepy need to have access to a galaxy catalog. Currently, the only supported catalog is GLADE+. You'll find the download link on this webpage : https://glade.elte.hu.
To prepare it for usage by tilepy we provide a the `ConvertGalaxyCatalog.py` script that converts the original catalog into a hdf5 file compatible with tilepy. The script is located in the `tilepy/tools` repository.

Example: use the script to keep only galaxies that are within 500 Mpc (recommended). It reads the downloaded `GLADE+.txt` file and creates the output file `Gladeplus.h5` which is the one that should be used with tilepy. You'll be able to specify the path to that file in your tilepy configuration. The examples assume the `Gladeplus.h5` to be located in the `tilepy/dataset/` directory.

```bash
python ConvertGalaxyCatalog.py --input GLADE+.txt --output Gladeplus.h5 --max-luminosity-distance 500
```

## Description

Package including functions to perform GW follow-up scheduling and simulations in IACTS. The package can be found in the folder tilepy, which contains the following folders:

- src/tilepy: Folder including the python package
    - tilepy.include: The main files were functions are placed. In the usual case, the manager script is ObservationScheduler.py. At the following level, we have TilingDetermination.py. And the base set of functions are in CampaignDefinition.py, Observatories.py, PointingPlotting.py, PointingTools.py and RankingObservationTimes.py.
    - tilepy.tools: Includes several scripts that have been used so far for different aims related to visualization and catalog cleaning
    - tilepy.scripts: Further support scripts

- github/workflows: a series of workflows are enabled and triggered via GitHub Actions.
- docs: files to create a documentation [dev ongoing]

- examples: Examples on how to use tilepy, see dedicated <a href="examples/README.md">README</a>
    - launcher: Jupyter notebooks and .py scripts to run observation schedules for various use-cases. We recommend to use the Jupyter notebooks as these are more comprehensive, specially with the inputs given.
    - paperplots: Precise plots of ApJS Series, Volume 274 Number 1 (11pp), 2024 September
    - sciencecases: Support material and extra plots connected to those of the paper ApJS Series, Volume 274 Number 1 (11pp), 2024 September
    - visualization: Several notebooks to improve the visualization of observation campaigns
    - config: various examples of configuration files, used in the notebooks to run the scripts. The format is the following:
       - [observatory]
          - name: name of the observatory (it is not critical, you can use any name)
          - lat: lat coordinates of the observatory
          - lon: lon coordinates of the observatory
          - height: height of the observatory

        - [visibility]
          - sunDown: altitude of the Sun in deg to define darkness conditions (for astronomic darkness sunDown= -18)
          - moonDown: altitude of the Moon in deg to define darkness conditions (for astronomic darkness moonDown= -0.5)
          - moonGrey: altitude of the Moon in deg to define greyness conditions
          - moonPhase: phase of the Moon to define greyness conditions
          - minMoonSourceSeparation: minimum separation Source-Moon in deg to define greyness conditions
          - maxMoonSourceSeparation: max separation Source-Moon in deg to define greyness conditions

        - [operations]
          - maxZenith: max zenith angle which will be considered as accessible sky
          - FOV: radius of the circular FoV defining the tiles
          - maxRuns: maximum number of tiles that will be scheduled
          - maxNights: total number of nights considered
          - duration: standard exposure per tile
          - minDuration: minimal duration of tile if standard exposure is not available (e.g. at the end of the night)
          - useGreytime: flag to schedule greyness observations in addition to darkness

        - [tiling]

          - minimumProbCutforCatalogue: only galaxies that have probabilities higher than 'minimumProbCutforCatalogue x (GW x galaxy)_max' participate in the scheduling calculation
          - minProbcut:  minimal probability covered per tile to schedule observation
          - distCut: distance cut to define the mandatory use of 2D strategy (coming from galaxy catalogue completeness)
          - doPlot: produce detailed plots of the scheduling
          - secondRound: consider two maps for scheduling
          - zenithWeighting: weight on probability that would be applied to prioritize coordinates that have lower zenith angle values. Step size is 5 deg in zenith (0.75 is a reasonable value)
          - percentageMOC: percentage of the sky localization region that will be considered to compute the MOC
          - reducedNside: nside of the low-resolution skymap used as a grid to speed up the computation
          - HRnside: nside of the high-resolution skymap used to compute the covered probability
          - mangrove: flag to use the mangrove method of weighting by the mass of the host galaxy
          - countPrevious: True if you want previous observation to be considered in number to set the max run variable. False else

## Issue with Daily Earth Orientation Parameters Solutions file (finals2000A)

Astropy requires a recent reference file to compute correctly the coordinates. This file is in general downloaded automatically by Astropy but if you are offline, you will be able to run tilepy if you do the following fix in a global variable.
First you need to download the file, it is available through several sources, IERS, OBSPM, NASA, USNO, .... For a fully offline installation, try to update the file every few month.

You need then to modify your script calling tilepy by adding the following lines before importing tilepy. Adapt the path to the file (here pathToYourReferencefile) in order that the system is able to find the file and loaded correctly.

```python
import os
from astropy.utils import iers
iers_file = os.path.join(os.path.abspath(
    os.path.dirname(__file__)), pathToYourReferencefile)
iers.IERS.iers_table = iers.IERS_A.open(iers_file)
```

## Help
If you find any problem, please open a new issue in the project main page to document it. You can of course also directly create a Pull Request with new features.

Otherwise you can also contact us at `astro.tilepy@gmail.com`
A user/developer discussion forum is available at `https://forum.astro-colibri.science/c/instrumentation-and-tools/tilepy`
