AstroLib

Documentation	Package Evaluator	Build Status	Code Coverage

Goal

The aim of this project is to provide users with a set of small generic routines useful above all in astronomical and astrophysical context, written in Julia.

Included are also translations of some IDL Astronomy User's Library procedures, which are released under terms of BSD-2-Clause License. AstroLib.jl's functions are not drop-in replacement of those procedures, Julia standard data types are often used (e.g., DateTime type instead of generic string for dates) and the syntax may slightly differ. Refer to the documentation of the functions for details.

Note: this project is a work-in-progress, only few procedures have been translated so far. In addition, function syntax may change from time to time. Check TODO.md out to see how you can help. Volunteers are welcome!

Installation

AstroLib.jl is available for Julia 1.0 and later versions, and can be installed with Julia built-in package manager. In a Julia session, after entering the package manager mode with ], run the command

pkg> add AstroLib

Older versions of this package are also available for Julia 0.4-0.7.

Note that, in order to work, a few functions require external files, which are automatically downloaded when building the package. Should these files be missing for some reason, you will be able to load the package but some functions may not work properly. You can manually build the package with

julia> Pkg.build("AstroLib")

Usage

After installing the package, you can start using it with

using AstroLib

Many functions in AstroLib.jl are compatible with Measurements.jl package, which allows you to define quantities with uncertainty and propagate the error when performing calculations according to propagation of uncertainty rules. For example:

using AstroLib, Measurements
mag2flux(12.54 ± 0.03)
# => 3.499451670283562e-14 ± 9.669342299577655e-16

New Types

Observatory

AstroLib.jl defines a new Observatory type. This can be used to define a new object holding information about an observing site. It is a composite type whose fields are

name (String type): the name of the site
latitude (Float64 type): North-ward latitude of the site in degrees
longitude (Float64 type): East-ward longitude of the site in degrees
altitude (Float64 type): altitude of the site in meters
tz (Float64 type): the number of hours of offset from UTC

The type constructor Observatory can be used to create a new Observatory object. Its syntax is

Observatory(name, lat, long, alt, tz)

name should be a string; lat, long, and tz should be anything that can be converted to a floating number with ten function; alt should be a real number.

A predefined list of some observing sites is provided with AstroLib.observatories constant. It is a dictionary whose keys are the abbreviated names of the observatories. For example, you can access information of the European Southern Observatory with

julia> obs = AstroLib.observatories["eso"]
Observatory: European Southern Observatory
latitude:    -29.256666666666668°N
longitude:   -70.73°E
altitude:    2347.0 m
time zone:   UTC-4

julia> obs.longitude
-70.73

You can list all keys of the dictionary with

keys(AstroLib.observatories)

Feel free to contribute new sites or adjust information of already present ones.

Planet

The package provides Planet type to hold information about Solar System planets. Its fields are

Designation:
- name: the name
Physical characteristics:
- radius: mean radius in meters
- eqradius: equatorial radius in meters
- polradius: polar radius in meters
- mass: mass in kilogram
Orbital characteristics (epoch J2000):
- ecc: eccentricity of the orbit
- axis: semi-major axis of the orbit in meters
- period: sidereal orbital period in seconds

The constructor has this syntax:

Planet(name, radius, eqradius, polradius, mass, ecc, axis, period)

The list of Solar System planets, from Mercury to Pluto, is available with AstroLib.planets dictionary. The keys of this dictionary are the lowercase names of the planets. For example:

julia> AstroLib.planets["mercury"]
Planet:            Mercury
mean radius:       2.4397e6 m
equatorial radius: 2.4397e6 m
polar radius:      2.4397e6 m
mass:              3.3011e23 kg
eccentricity:      0.20563069
semi-major axis:   5.790905e10 m
period:            5.790905e10 s

julia> AstroLib.planets["mars"].eqradius
3.3962e6

julia> AstroLib.planets["saturn"].mass
5.6834e26

Documentation

Every function provided has detailed documentation that can be accessed at Julia REPL with

julia> ?FunctionName

or with

julia> @doc FunctionName

Full documentation of all functions can be accessed at http://juliaastro.github.io/AstroLib.jl/dev/. There you can find the complete list of all functions provided by this library.

How Can I Help?

You can contribute to the project in number of ways. You can translate more routines from IDL Astronomy User's Library or provide brand-new functions and improve existing ones. Also bug reports are encouraged.

Related Projects

This is not the only effort to bundle astronomical functions written in Julia language. Other packages useful for more specific purposes are available at https://juliaastro.github.io/.

In addition, there are similar projects for Python (Python AstroLib) and R (Astronomy Users Library).

License

The AstroLib.jl package is licensed under the MIT "Expat" License. The original author is Mosè Giordano.

JuliaAstro/AstroLib.jl