****************************************************
User guide to program with guitastro Python classes
****************************************************

This section show how to use guitastro in a Python code.

1. Context
**********

Celestial mechanics allow to 
compute celestial bodies positions and manage dates, durations, angles, coordinates

2. Python classes provided by guitastro
***************************************

Brief descrition of the guitastro classes:

	* Angle: Convert angles in complex formats.
	* Coords: Convert angles in complex formats.
	* Home: Define a mount location on the Earth surface.
	* Horizon: Define horizon line to set the limits of telescope pointings.
	* Atmosphere: Define atmospheric conditions to set the conditions to compute refraction effects.
	* Site: Define an observation site by merging Home, Horizon, Atmosphere.
	* Date: Convert dates in complex formats.
	* Duration: Convert durations in complex formats.
	* Mechanics: Low level methods for celestial mechanics
	* Targets: High level methods for celestial mechanics
	
.. image:: doc_images/generated/classes_guitastro.png

.. image:: doc_images/generated/packages_guitastro.png

3. Using the Python module guitastro for angles
************************************************

3.1. Simple example to convert angles
=====================================

.. code-block:: python

	import guitastro
	a = guitastro.Angle("2h3m27s")
	print("angle deg =", a.deg())

angle deg = 30.862499999999994

3.2. Operation with angles
==========================

We want to compute sum of the angles 2h3m27s and -0d28m12.4s. Display the results in sexagesimal format expressed in degrees:

.. code-block:: python
 
	import guitastro
	a = guitastro.Angle("2h3m27s")
	b = guitastro.Angle("-0d28m12.4s")
	c = a + b
	print("{}".format(c.sexagesimal("d")))

'30d23m32.60s'

4. Using the Python module guitastro for dates
**********************************************

Celme module is located in the folder pyros/src/utils
Examples: pyros/src/utils/report/dates.py
help(Date)

4.1. Simple example to convert dates
====================================

.. code-block:: python

	import guitastro
	a = guitastro.Date("now")
	print("Date ISO =", a.iso())
	Date ISO = 2018-10-11T22:45:44.958
	print("Date Julian Day =", a.jd())

Date Julian Day = 2458403.448437011

4.2. Operation with dates
=========================

We want to compute date corresponding to add 2 days and 28 minutes to the 2018-10-11T22:45:44.958. Display the results in ISO format:

.. code-block:: python
 
	import guitastro
	a = guitastro.Date("2018-10-11T22:45:44.958")
	b = guitastro.Duration("2d28m")
	c = a + b
	print("Date ISO =", c.iso())

Date ISO = 2018-10-13T23:13:44.958

5. Using the Python module guitastro for ephemeris
**************************************************

| Celme module is located in the folder pyros/src/utils
| Examples: pyros/src/utils/report/targets.py

.. code-block:: python

	help(Target)

5.1. Simple example to compute Sun coordinates
==============================================

First we compute RA, DEC coordinates of the Sun:

.. code-block:: python

	import guitastro
	date = guitastro.Date("now")
	site = guitastro.Site("GPS 0 E 49 200")
	skyobj= {'planet':'Sun'}
	target = guitastro.Target()
	target.define(skyobj)
	output0s = ['ra','dec']
	results = target.ephem(date,site,output0s)
	ra = results['RA']
	dec = results['DEC']

Second, we inject RA, DEC to compute its local coordinates:

.. code-block:: python

	skyobj= {'RA':ra , 'DEC':dec }
	outputs = ['elev']
	target.define(skyobj)
	results = target.ephem(date,site,outputs)
	elev = results['ELEV']

6. Angle formats
****************

Input accepted formats:

| -12.345 : Decimal degrees
| -0.3421r : Decimal radians
| 6h3m2s : Sexagesimal HMS
| 3mh2s : Sexagesimal MS
| 2sh : Sexagesimal S
| 6d3m2s : Sexagesimal dms
| 3m2s : Sexagesimal ms
| 2s : Sexagesimal s (i.e. arcsec)
| “6 3 2” : Sexagesimal dms
| “6:3:2” : Sexagesimal dms
| “6h3:2” : Sexagesimal HMS

Sexagesimal formating using uspzad convention rad is an angle in radian
Sexagesimal format:

	* u (unit) = h,H,d,D (default=D). Capital mean module [0:360[, lower case means module [-180:180[ 
	* s (separator) = " ",:,"" (default="" means letters hms or dms)
	* p (plus/minus) = +,"" (default="")
	* z (zeros) = 0,"" (default="")
	* a (angle_limits) = "",90, (+/-limit if unit D,H, default="" means 360)
	* d (sec_digits) = "",".1",".2",... (default="")

Style 1:

	* To Display a R.A.: "H0.2" =>  23h07m42.49s
	* To Display a Decl.: "d+090.1" => +00d34m22.6s
	* To Display a H.A.: "h0.2" => -08h43m16.05s

Style 2:

	* To Display a R.A.: "H 0.2" =>  23 07 42.49
	* To Display a Decl.: "d +090.1" => -00 34 22.6
	* To Display a H.A.: "h 0.2" => -08 43 16.05

Style 3:

	* To Display a R.A.: "H:0.2" =>  23:07:42.49
	* To Display a Decl.: "d:+090.1" => -00:34:22.6
	* To Display a H.A.: "h:0.2" => -08:43:16.05

7. Date formats
****************

Input accepted formats:

* now = Now. e.g. "now"    
* jd = Julian day. e.g. 24504527.45678
* iso = ISO 8601. e.g. 2018-02-28T12:34:55.23
* sql = ISO 8601. e.g. 2018-02-28 12:34:55.23
* ymdhms = Calendar. e.g. 2018 2 28 12 34 55.23
* equinox = Equinox. e.g. J2000,0
* digits = Pure digits e.g. 20180228123455.23