slrfield 0.2.1
A package to handle the SLR(Satellite Laser Ranging) data
License: MIT
Requires Python: >=3.8
Keywords: SLR,CPF

# Welcome to the SLRfield package

[![PyPI version shields.io](https://img.shields.io/pypi/v/slrfield.svg)](https://pypi.python.org/pypi/slrfield/) [![PyPI pyversions](https://img.shields.io/pypi/pyversions/slrfield.svg)](https://pypi.python.org/pypi/slrfield/) [![PyPI status](https://img.shields.io/pypi/status/slrfield.svg)](https://pypi.python.org/pypi/slrfield/) [![GitHub contributors](https://img.shields.io/github/contributors/lcx366/SLRfield.svg)](https://GitHub.com/lcx366/SLRfield/graphs/contributors/) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/lcx366/SLRfield/graphs/commit-activity) [![GitHub license](https://img.shields.io/github/license/lcx366/SLRfield.svg)](https://github.com/lcx366/SLRfield/blob/master/LICENSE) [![Documentation Status](https://readthedocs.org/projects/pystmos/badge/?version=latest)](http://slrfield.readthedocs.io/?badge=latest) [![Build Status](https://travis-ci.org/lcx366/SLRfield.svg?branch=master)](https://travis-ci.org/lcx366/SLRfield)

This package is an archive of scientific routines for data processing related to SLR(Satellite Laser Ranging). 
Currently, operations on SLR data include:

1. Download CPF(Consolidated Prediction Format) ephemeris files automatically from **CDDIS**(Crustal Dynamics Data Information System) or **EDC**(EUROLAS Data Center);
2. Parse the CPF ephemeris files;
3. Predict the positions of targets in topocentric reference frame, and compute the time of flight for laser pulse;
4. Calculate the position of targets in GCRF;

## How to Install

On Linux, macOS and Windows architectures, the binary wheels can be installed using pip by executing one of the following commands:

```
pip install slrfield
pip install slrfield --upgrade # to upgrade a pre-existing installation
```

## How to use

### Download the latest CPF ephemeris files at the current moment

If the ephemeris release center is not provided, the CPF ephemeris files are downloaded from **CDDIS** by default.

#### Download all currently available targets

```python
>>> from slrfield import cpf_download
>>> cpf_dir_cddis,cpf_files_cddis = cpf_download() # From CDDIS by default;
>>> print(cpf_dir,cpf_files)
```

A directory where CPF files are stored, such as *CPF/CDDIS/2020-10-02/*, will be automatically created.

#### Download a set of targets which are specified by user

```python
>>> sat_lists = ['ajisai','lageos1','etalon2','jason3']
>>> cpf_dir_edc,cpf_files_edc = cpf_download(sat_lists,source = 'EDC',keep=False) # From EDC
```

Note: by setting `keep = False`, the cpf files storage directory will be automatically ***emptied*** beforehand.

### Download the latest CPF ephemeris files before a specific date and time

```python
>>> sat_lists = ['starlette','lageos1']
>>> date = '2017-01-01 11:30:00'
>>> cpf_dir_cddis,cpf_files_cddis = cpf_download(sat_lists,date)
```

### Parse the CPF ephemeris files and read the data

Information from the parsed CPF ephemeris files includes the following contents:

- Format
- Format Version
- Ephemeris Source
- Date and time of ephemeris production
- Ephemeris Sequence number
- Target name
- COSPAR ID
- SIC
- NORAD ID
- Starting date and time of ephemeris
- Ending date and time of ephemeris
- Time between table entries (UTC seconds)
- Target type
- Reference frame
- Rotational angle type
- Center of mass correction
- Direction type
- Modified Julian Date
- Second of Day 
- Leap Second
- Time moment in UTC 
- Target positions in meters

#### Parse CPF ephemeris files

```python
>>> from slrfield import CPF
>>> cpf_data_cddis = CPF.from_files(cpf_dir_cddis)
>>> print(cpf_data_cddis.info)
```

### Make predictions w.r.t. a site

The azimuth, altitude, distance of a target w.r.t. a given site, and the time of flight for laser pulse etc. can be easily predicted by calling a method `pred_azalt`. The output prediction files named with target names are generated by default. 

- There are two modes for the prediction. If the mode is set to ***geometric***, then the transmitting direction of the laser will coincide with the receiving direction at a certain moment. In this case, the output prediction file will not contain the difference between the receiving direction and the transmitting direction. If the mode is set to ***apparent***, then the transmitting direction of the laser is inconsistent with the receiving direction at a certain moment. In this case, the output prediction file will contain the difference between the receiving direction and the transmitting direction. The default mode is set to ***apparent***.
- The 10-point(degree 9) Lagrange polynomial interpolation method is used to interpolate the CPF ephemeris.
- Effects of leap second have been considered in the prediction generation.

Coordinates of station can either be ***geocentric***(x, y, z) in meters or ***geodetic***(lon, lat, height) in degrees and meters. The default coordinates type is set to ***geodetic***.

#### For geodetic(lon, lat, height) site coordinates

```python
t_start = '2017-01-02 17:06:40'
t_end = '2017-01-03 09:06:40'
t_increment = 0.5 # second

station = [46.877230,7.465222,951.33] # geodetic(lon, lat, height) coordinates in degrees and meters by default
cpf_data_cddis.pred_azalt(station,t_start,t_end,t_increment)
```

#### For geocentric(x, y, z) site coordinates

```python
t_start = '2017-01-02 17:06:40'
t_end = '2017-01-03 09:06:40'
t_increment = 2 # second

station = [4331283.557, 567549.902,4633140.353] # geocentric(x, y, z) coordinates in meters
cpf_data_cddis.pred_azalt(station,t_start,t_end,t_increment,coord_type = 'geocentric',mode='geometric')
```

### Make predictions in GCRF

The cartesian coordinates of targets in GCRF(Geocentric Celestial Reference Frame) can be easily predicted by calling a method `pred_xyz`.

```python
t_start = '2017-01-02 17:06:40'
t_end = '2017-01-03 09:06:40'
t_increment = 5 # second

cpf_data_cddis.pred_xyz(t_start,t_end,t_increment)
```

## Change log

- **0.2.1 — jul 16, 2023**
  - Added time system for loading/updating the EOP file and Leap Second file from IERS

- **0.2.0 — Feb 24, 2022**
  
  - Added support for calculating the cartesian coordinates of targets in GCRF
  
  - Added support for quickly computing the passing-site prediction 
  
  - Removed the module related to TLE data
  
  - Removed the module related to satellite catalog querying 

- **0.1.17 — Nov 04,  2021**
  
  - Fixed the problem of response failure caused by accessing a large amount of data from discos remote server using API
  - Fixed the problem that requested URL's length exceeds the capacity limit of the space-track server.
  - Change the process printing style of query from static to dynamic with color
  - Added support for orbital eccentricity in celestrak_query and target_query, including options of filtering and sorting
  - Added support for output of standard(intrinsic) magnitudes of targets in target_query

- **0.1.14 — Jun 18,  2021**
  
  Fixed the problem that EOP could not be downloaded normally from IERS.

- **0.1.13 — Jun 05,  2021**
  
  Now you may inject the NORAD IDs of a large number of targets by an input file such as *noradids.txt* to  `target_query`.

- **0.1.11 — Oct 03,  2020**
  
  The CDDIS will discontinue anonymous ftp access to its archive in October 2020, therefore, this package implements the transition from ftp to EARTHDATA for downloading CPF files.

- **0.1.9 — Jul 26,  2020**
  
  Added progress bar for downloading data

- **0.1.5 — Jun 9,  2020**
  
  Expanded the following functions：
  
  - Automatically download TLE/3LE data from [SPACETRACK](https://www.space-track.org)
  - Pick out space targets that meets specific demands from [DISCOS](https://discosweb.esoc.esa.int)(Database and Information System Characterising Objects in Space) and [CELESTRAK](https://celestrak.com) database by setting a series of parameters, such as mass, shape, RCS(Radar Cross Section), and orbit altitude etc.
  - Calculate one-day prediction and multiple-day visible passes for space targets based on TLE/3LE data

- **0.0.2 — Apr 21,  2020**
  
  - The ***slrfield*** package was released.

## Next release

- Add functions to download and parse the CRD(**Consolidated Laser Ranging Data Format**) observations

## Reference

- [Python package for satellite laser ranging file formats](https://github.com/dronir/SLRdata)
- [Consolidated Laser Ranging Prediction Format Version 1.01](https://ilrs.gsfc.nasa.gov/docs/2006/cpf_1.01.pdf)
- [sample code](https://ilrs.gsfc.nasa.gov/docs/2017/cpf_sample_code_v1.01d.tgz) on [ILRS](https://ilrs.gsfc.nasa.gov/data_and_products/formats/cpf.html)