# About
**helisol** is a Python 3 package that calculates precisely the earth trajectory (tilt, longitude, true anomaly etc.) and absolute and apparent sun position (declination, right ascension, height above horizon, azimuth etc.) in the sky seen from any specified position on Earth and at any time. Sunset, solar noon, and sunrise times are also provided. It uses Meeus' equations including perturbations from planets on the earth orbit.
- `Earth` describes the motion of earth around the sun
- `Sun` describes the position of the sun seen from earth, irrespective of exact location on earth (declination, equation of time, etc.)
- `SunObservation` describes the position of the sun in the sky as observed at a given location on earth (azimuth, height, etc.).
The package also includes tools to store and manipulate angles (`Angle` class) and times (`Time` class), and a function to calculate refraction effects (`refraction()`).
See *ExampleShadow.ipynb* for an example on how to use the package to calculate the shadow of an object at different times of the year.
*SOON*:
- Sundial calculation and generation
**Precision** can be evaluated by comparison to published ephemerids. We have used ephemerids for March 2023 for sunset / sunrise and solar noon, and ephemerids for August 2023 for right ascension, declination and equation of time (see test file).
- Sunset, sunrise and solar noon are within the displayed precision of each other (1 second for noon, 1 minute for sunset/sunrise)
- Right ascension and equation of time are within the displayed precision of each other (1 second in time)
- Declination deviates less than 2.5 arc-seconds (0.0007°, or 0.17 seconds in time).
- Sun to Earth distance deviates less than 1600 km; extracted aphelion and perihelion dates extracted from the extrema of this distance seem to be off by a few hours depending on the year.
# Install
```bash
pip install helisol
```
# Usage
## Earth position and orbit
```python
from helisol import Earth
# Get current axial tilt and true anomaly of the earth
earth = Earth()
earth.true_anomaly
earth.orbit.axial_tilt
# Get properties at a given date
earth = Earth('Sept. 9, 2003')
# Update to current time
earth.update()
# Update to specific time
earth.update(utc_time='2023-03-21, 12:00')
# Min and max sun-eath distance
Earth(2019).orbit.perihelion() # specific year
Earth().orbit.aphelion() # current year
```
## Sun absolute position
```python
from helisol import Sun
# Get current sun position
sun = Sun()
sun.declination
sun.right_ascension
sun.equation_of_time
# Access earth object associated with sun
sun.earth
# Get sun at specific UTC time and then update to current time
sun = Sun('March 3, 13:30')
sun.update()
```
## Sun viewed from given location on earth
```python
from helisol import SunObservation
# Get current position of the sun
# NOTE: location can be a tuple of coords, a location name (if stored in the
# JSON database), or a location object (see below).
obs = Sun(location=(42.4, -76.5))
print(obs) # Some info (azimuth height, sunrise etc. is printed here)
# Update position to current time
obs.update()
print(obs)
# Update position to specified time and date
obs.update(utc_time='Jan 6, 2023, 4:25:03pm')
print(obs.height) # Height above horizon, in degrees
print(obs.azimuth) # azimuth with respect to south in degrees
# It is possible to specify time upon instantiation directly:
obs = Sun(location=(42.4, -76.5), utc_time='2023-1-6, 16:25:03')
# sunrise, noon (meridian), sunset [center of sun, no refraction]
print(obs.sunrise, obs.noon, obs.sunset)
# To include refraction and other options to calculate sunrise / sunset:
obs.actual_sunrise() # [top of sun, with refraction]
obs.actual_sunrise(point='center') # [center of sun, with refraction]
obs.actual_sunrise(refract=False, point='bottom') # [sun bottom, no refract]
obs.actual_sunrise(obstacle=Angle(26)) # with an obstacle of 26° of height
# The method also exists for sunset:
obs.actual_sunset()
# (NOTE: options for the precision of the calculation also exists, see docstring)
# Access sun object associated with the observation:
obs.sun
```
## Angles
```python
from helisol import Angle, sin, cos, tan
a = Angle(degrees=30.7)
sin(a)
a.sin() # equivalent to line above
b = Angle(radians=np.pi/4)
tan(b)
c = Angle(degrees=3, minutes=45, seconds=10) # °, ', "
cos(c)
d = Angle(hms=(8, 44, 43)) # in hours, min, sec
e = Angle.arctan(1) # pi/4
# Allowed operations
a + b
a - b
a * 2
2 * a
a / 2
- a
a < b
a == b
# and other comparisons
# And combinations, e.g.
(a - b) / 4
cos(2 * a - b)
# access values in different units (decimal)
a.radians
a.degrees
# Read-only info on minutes and seconds of angle
a.minutes
a.seconds
# Read_only info on time in hours (min/sec):
a.hms
```
If having performance issues with `Angle`, it is possible to increase speed by shortcutting tests of units during instantiation, using more specialized `Angle` subclasses:
```python
from helisol import AngleFromDegrees, AngleFromRadians
from helisol import AngleFromMinutes, AngleFromSeconds
a = AngleFromDegrees(30)
b = AngleFromRadians(np.pi / 6)
c = AngleFromMinutes(1.5)
d = 90 * AngleFromSeconds(1)
a - b + c - d
```
It is also possible to use arrays with the `AngleArray` class, e.g.
```python
from helisol import AngleArray
a = AngleArray(degrees=[44.5, 2.5, 3], minutes=[30, 30, 0])
a.tan()
```
## Distances
Distances are managed by the `Distance` class
```python
from helisol import Distance
d = Distance(au=2.5) # 2.5 astronomical units
d.m
d.km
d.au
```
## Date / times
```python
from helisol import Time
time = Time(utc_time='2022, July 3, 6:12')
time.utc # datetime with no timezone (implicitly UTC)
time.julian_years # Julian years since Jan 1 2000, 12:00
time.fraction_of_day # 0 for midnight, 0.5 for noon
# It is possible to manually adjust the fraction of day to set the time:
time.fraction_of_day = 0.5
# It is also possible to instantiate a Time object with a fraction of day
time = Time(utc_time='2023, March 10', fraction_of_day=0.25) # 6am
# To obtain a rounded version of time:
time.rounded_to('second')
time.rounded_to('minute')
```
## Refraction
```python
from helisol import Angle, refraction
# When true height is at horizon level (29' approx.)
refraction(true_height=Angle(0))
# When apparent height is at horizon level (34' approx)
refraction(apparent_height=Angle(0))
# At arbitrary true height or apparent heights
refraction(Angle(23)) # true height of 23 degrees
refraction(true_height=Angle(degrees=23)) # same thing
refraction(apparent_height=Angle(minutes=66)) # apparent height of 10'
```
## Generate tables of data
It is possible to generate tables (pandas DataFrames) containing sun position data, or sunset/sunrise data between selected dates and with selected frequency, with the functions:
- `generate_table()`
- `extend_table()`
- `sunset_table()`
(see docstrings for help and examples).
## Location management
It is possible to save/load location information with the `Location` class.
```python
From helisol import Location, SunObservation
# Load existing location and use it to instantiate a Sun object
location = Location.load('Home')
obs = SunObservation(location)
# equivalently:
obs = SunObservation('Home')
# It is possible to configure a default location in config.py (default 'Home')
# so that one can do just
SunObservation()
# Define custom location and save it in the database
# NOTE: it is possible to define elevation, although not used in helisol at
# the moment.
location = Location(name='Work', coords=(40.78, -73.97))
location.save() # save in a non-shared file (excluded from version )
location.save('global') # save in globals.json file, version controlled.
# Remove location from database:
location.remove('Work')
```
# Requirements
Python >= 3.7
*Packages*
- numpy
- pandas
- oclock
# Author
Olivier Vincent
(ovinc.py@gmail.com)
# Contributors
Gilbert Vincent (equations and advice)
# References
- Meeus, J., *Calculs astronomiques à l’usage des amateurs*, Société astronomique de France (2014).
- Saemundsson, T., *Astronomical Refraction*, Sky and Telescope, **72**, 70 (1986).
- Bennett, G. G., *The calculation of astronomical refraction in marine navigation*, Journal of Navigation, **35**, 255-259 (1982).
# License
GNU GPLv3, see *LICENSE* file
Raw data
{
"_id": null,
"home_page": "https://github.com/ovinc/helisol",
"name": "helisol",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "sun,position,azimuth,height,sunset,sunrise,noon,sundial,astronomy,angle,time",
"author": "Olivier Vincent",
"author_email": "ovinc.py@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/75/45/4a1e10f916a50b7274acac37fb886f67bcdc9b09fd61c3e1471e25ae2c25/helisol-0.5.1.tar.gz",
"platform": null,
"description": "# About\n\n**helisol** is a Python 3 package that calculates precisely the earth trajectory (tilt, longitude, true anomaly etc.) and absolute and apparent sun position (declination, right ascension, height above horizon, azimuth etc.) in the sky seen from any specified position on Earth and at any time. Sunset, solar noon, and sunrise times are also provided. It uses Meeus' equations including perturbations from planets on the earth orbit.\n\n- `Earth` describes the motion of earth around the sun\n\n- `Sun` describes the position of the sun seen from earth, irrespective of exact location on earth (declination, equation of time, etc.)\n\n- `SunObservation` describes the position of the sun in the sky as observed at a given location on earth (azimuth, height, etc.).\n\nThe package also includes tools to store and manipulate angles (`Angle` class) and times (`Time` class), and a function to calculate refraction effects (`refraction()`).\n\nSee *ExampleShadow.ipynb* for an example on how to use the package to calculate the shadow of an object at different times of the year.\n\n*SOON*:\n- Sundial calculation and generation\n\n**Precision** can be evaluated by comparison to published ephemerids. We have used ephemerids for March 2023 for sunset / sunrise and solar noon, and ephemerids for August 2023 for right ascension, declination and equation of time (see test file).\n\n- Sunset, sunrise and solar noon are within the displayed precision of each other (1 second for noon, 1 minute for sunset/sunrise)\n\n- Right ascension and equation of time are within the displayed precision of each other (1 second in time)\n\n- Declination deviates less than 2.5 arc-seconds (0.0007\u00b0, or 0.17 seconds in time).\n\n- Sun to Earth distance deviates less than 1600 km; extracted aphelion and perihelion dates extracted from the extrema of this distance seem to be off by a few hours depending on the year.\n\n\n# Install\n\n```bash\npip install helisol\n```\n\n# Usage\n\n## Earth position and orbit\n\n```python\nfrom helisol import Earth\n\n# Get current axial tilt and true anomaly of the earth\nearth = Earth()\nearth.true_anomaly\nearth.orbit.axial_tilt\n\n# Get properties at a given date\nearth = Earth('Sept. 9, 2003')\n\n# Update to current time\nearth.update()\n\n# Update to specific time\nearth.update(utc_time='2023-03-21, 12:00')\n\n# Min and max sun-eath distance\nEarth(2019).orbit.perihelion() # specific year\nEarth().orbit.aphelion() # current year\n```\n\n\n## Sun absolute position\n\n```python\nfrom helisol import Sun\n\n# Get current sun position\nsun = Sun()\nsun.declination\nsun.right_ascension\nsun.equation_of_time\n\n# Access earth object associated with sun\nsun.earth\n\n# Get sun at specific UTC time and then update to current time\nsun = Sun('March 3, 13:30')\nsun.update()\n```\n\n\n## Sun viewed from given location on earth\n\n```python\nfrom helisol import SunObservation\n\n# Get current position of the sun\n# NOTE: location can be a tuple of coords, a location name (if stored in the\n# JSON database), or a location object (see below).\nobs = Sun(location=(42.4, -76.5))\nprint(obs) # Some info (azimuth height, sunrise etc. is printed here)\n\n# Update position to current time\nobs.update()\nprint(obs)\n\n# Update position to specified time and date\nobs.update(utc_time='Jan 6, 2023, 4:25:03pm')\nprint(obs.height) # Height above horizon, in degrees\nprint(obs.azimuth) # azimuth with respect to south in degrees\n\n# It is possible to specify time upon instantiation directly:\nobs = Sun(location=(42.4, -76.5), utc_time='2023-1-6, 16:25:03')\n\n# sunrise, noon (meridian), sunset [center of sun, no refraction]\nprint(obs.sunrise, obs.noon, obs.sunset)\n\n# To include refraction and other options to calculate sunrise / sunset:\nobs.actual_sunrise() # [top of sun, with refraction]\nobs.actual_sunrise(point='center') # [center of sun, with refraction]\nobs.actual_sunrise(refract=False, point='bottom') # [sun bottom, no refract]\nobs.actual_sunrise(obstacle=Angle(26)) # with an obstacle of 26\u00b0 of height\n# The method also exists for sunset:\nobs.actual_sunset()\n# (NOTE: options for the precision of the calculation also exists, see docstring)\n\n# Access sun object associated with the observation:\nobs.sun\n```\n\n## Angles\n\n```python\nfrom helisol import Angle, sin, cos, tan\n\na = Angle(degrees=30.7)\nsin(a)\na.sin() # equivalent to line above\n\nb = Angle(radians=np.pi/4)\ntan(b)\n\nc = Angle(degrees=3, minutes=45, seconds=10) # \u00b0, ', \"\ncos(c)\n\nd = Angle(hms=(8, 44, 43)) # in hours, min, sec\n\ne = Angle.arctan(1) # pi/4\n\n# Allowed operations\na + b\na - b\na * 2\n2 * a\na / 2\n- a\na < b\na == b\n# and other comparisons\n\n# And combinations, e.g.\n(a - b) / 4\ncos(2 * a - b)\n\n# access values in different units (decimal)\na.radians\na.degrees\n\n# Read-only info on minutes and seconds of angle\na.minutes\na.seconds\n\n# Read_only info on time in hours (min/sec):\na.hms\n```\n\nIf having performance issues with `Angle`, it is possible to increase speed by shortcutting tests of units during instantiation, using more specialized `Angle` subclasses:\n\n```python\nfrom helisol import AngleFromDegrees, AngleFromRadians\nfrom helisol import AngleFromMinutes, AngleFromSeconds\na = AngleFromDegrees(30)\nb = AngleFromRadians(np.pi / 6)\nc = AngleFromMinutes(1.5)\nd = 90 * AngleFromSeconds(1)\na - b + c - d\n```\n\nIt is also possible to use arrays with the `AngleArray` class, e.g.\n```python\nfrom helisol import AngleArray\na = AngleArray(degrees=[44.5, 2.5, 3], minutes=[30, 30, 0])\na.tan()\n```\n\n## Distances\n\nDistances are managed by the `Distance` class\n\n```python\nfrom helisol import Distance\nd = Distance(au=2.5) # 2.5 astronomical units\nd.m\nd.km\nd.au\n```\n\n\n## Date / times\n\n\n```python\nfrom helisol import Time\n\ntime = Time(utc_time='2022, July 3, 6:12')\ntime.utc # datetime with no timezone (implicitly UTC)\ntime.julian_years # Julian years since Jan 1 2000, 12:00\ntime.fraction_of_day # 0 for midnight, 0.5 for noon\n\n# It is possible to manually adjust the fraction of day to set the time:\ntime.fraction_of_day = 0.5\n\n# It is also possible to instantiate a Time object with a fraction of day\ntime = Time(utc_time='2023, March 10', fraction_of_day=0.25) # 6am\n\n# To obtain a rounded version of time:\ntime.rounded_to('second')\ntime.rounded_to('minute')\n```\n\n## Refraction\n\n```python\nfrom helisol import Angle, refraction\n\n# When true height is at horizon level (29' approx.)\nrefraction(true_height=Angle(0))\n\n# When apparent height is at horizon level (34' approx)\nrefraction(apparent_height=Angle(0))\n\n# At arbitrary true height or apparent heights\nrefraction(Angle(23)) # true height of 23 degrees\nrefraction(true_height=Angle(degrees=23)) # same thing\nrefraction(apparent_height=Angle(minutes=66)) # apparent height of 10'\n```\n\n\n## Generate tables of data\n\nIt is possible to generate tables (pandas DataFrames) containing sun position data, or sunset/sunrise data between selected dates and with selected frequency, with the functions:\n- `generate_table()`\n- `extend_table()`\n- `sunset_table()`\n\n(see docstrings for help and examples).\n\n\n## Location management\n\nIt is possible to save/load location information with the `Location` class.\n\n```python\nFrom helisol import Location, SunObservation\n\n# Load existing location and use it to instantiate a Sun object\nlocation = Location.load('Home')\nobs = SunObservation(location)\n# equivalently:\nobs = SunObservation('Home')\n\n# It is possible to configure a default location in config.py (default 'Home')\n# so that one can do just\nSunObservation()\n\n# Define custom location and save it in the database\n# NOTE: it is possible to define elevation, although not used in helisol at\n# the moment.\nlocation = Location(name='Work', coords=(40.78, -73.97))\nlocation.save() # save in a non-shared file (excluded from version )\nlocation.save('global') # save in globals.json file, version controlled.\n\n# Remove location from database:\nlocation.remove('Work')\n```\n\n\n# Requirements\n\nPython >= 3.7\n\n*Packages*\n- numpy\n- pandas\n- oclock\n\n\n# Author\n\nOlivier Vincent\n(ovinc.py@gmail.com)\n\n# Contributors\n\nGilbert Vincent (equations and advice)\n\n# References\n\n- Meeus, J., *Calculs astronomiques \u00e0 l\u2019usage des amateurs*, Soci\u00e9t\u00e9 astronomique de France (2014).\n\n- Saemundsson, T., *Astronomical Refraction*, Sky and Telescope, **72**, 70 (1986).\n\n- Bennett, G. G., *The calculation of astronomical refraction in marine navigation*, Journal of Navigation, **35**, 255-259 (1982).\n\n\n# License\n\nGNU GPLv3, see *LICENSE* file\n\n\n",
"bugtrack_url": null,
"license": "GNU GPLv3",
"summary": "Get precise position of sun in sky (height, azimuth) at given location and time, get sunrise and sunset time, generate sundials.",
"version": "0.5.1",
"split_keywords": [
"sun",
"position",
"azimuth",
"height",
"sunset",
"sunrise",
"noon",
"sundial",
"astronomy",
"angle",
"time"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2504013f0190ef22217cefab5c6956de39370d756de57d96aecb55d1b51e41bd",
"md5": "440974081d6f472f069243fd2783e198",
"sha256": "e2c54d671425c6f08dba72ba0c96f7ed482e7c64dc8e897ea237e6ef59f2dccc"
},
"downloads": -1,
"filename": "helisol-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "440974081d6f472f069243fd2783e198",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 40578,
"upload_time": "2023-04-11T10:15:32",
"upload_time_iso_8601": "2023-04-11T10:15:32.596088Z",
"url": "https://files.pythonhosted.org/packages/25/04/013f0190ef22217cefab5c6956de39370d756de57d96aecb55d1b51e41bd/helisol-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75454a1e10f916a50b7274acac37fb886f67bcdc9b09fd61c3e1471e25ae2c25",
"md5": "5afa9604c39711fadebed10b3a700c89",
"sha256": "9bda39e56159da780c6ca963a28272ec77f7254195e017635f6890c7c6039c24"
},
"downloads": -1,
"filename": "helisol-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "5afa9604c39711fadebed10b3a700c89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 76938,
"upload_time": "2023-04-11T10:15:45",
"upload_time_iso_8601": "2023-04-11T10:15:45.370308Z",
"url": "https://files.pythonhosted.org/packages/75/45/4a1e10f916a50b7274acac37fb886f67bcdc9b09fd61c3e1471e25ae2c25/helisol-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-11 10:15:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ovinc",
"github_project": "helisol",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "helisol"
}
JSON
