[](https://celerity.observerly.com)
Celerity is a lightweight, research-grade, zero-dependency type-safe Python library for astronomical calculations to plan your observations. It's only dependency is the Python 3.11+ standard library.
It has been designed to be independent of any other popular astronomical libraries, with a focus on providing a simple and intuitive API for performing common astronomical calculations.
**N.B.** _This project is currently in the early stages of development and is not yet ready for production use._
---
## Usage
### Installation
Celerity can be installed using `pip`:
```console
pip install celerity
```
or `poetry`:
```console
poetry add celerity
```
### API
The API has been designed to be written in an idiomatic and natural way for English speakers, as well as idiomatic to Python.
It has been specifically designed to only depend on the core set of Python modules, such that it is not strictly dependent on other popular astronomical libraries, e.g., astropy (although it can compliment the usage of these libraries).
It's important to note that the API does not perform string parsing of times and coordinates, but instead requires the user to provide the correct data types. This is to ensure that the API is type-safe and that the user is aware of the data types being used at all times.
For example, to find out the horizontal coordinate for the star Betelgeuse on the 14th May 2021 at 12:00 UTC, at Mauna Kea, Hawaii, you would write:
```python
from datetime import datetime, timezone
from celerity import Observer, Time
# Mauna Kea, Hawaii:
observer = Observer(
latitude=19.82,
longitude=-155.47,
elevation=4205,
)
# Time of observation in UTC:
time = Time(
when=datetime(2021, 5, 14, 12, 0, 0, tzinfo=timezone.utc)
)
# Provide an equatorial target in equatorial coordinates at epoch J2000 in units of degrees:
betelgeuse = { ra: 88.792938, dec: 7.407064 }
# Observe the target:
betelgeuse = observer.at(time).observe({ ra: 88.792938, dec: 7.407064 })
# Get the horizontal coordinates:
{ alt, az } = betelgeuse.altAz()
# What is the Local Sidereal Time at the time of observation?
lst = observer.at(time).LST()
# What is the Julian Date at the time of observation?
jd = observer.at(time).JD()
```
### Notes & Caveats
Celerity is designed such that fundamental SI units of measurement are used, e.g., degrees, metres, seconds, etc. This is to ensure that the API is as accurate as possible, and that the user is aware of the units being used at all times.
The `Observer` class requires the user to provide the latitude and longitude in degrees, and the elevation in metres. Latitude is positive for the northern hemisphere, and negative for the southern hemisphere between -90° at the southern pole and +90° at the northern pole. Longitude is always positive for the eastern hemisphere (east of the Prime Meridian), and negative for the western hemisphere (west of the Prime Meridian) representing a longitude between -180° and +180°.
The `Time` class requires the user to provide the time in UTC, and not in any other timezone. The user can, once the `Time` object has been created, convert the time to any other timezone using the provided class methods.
The `Target` class requires the user to provide the right ascension and declination in degrees (and not in hours and degrees).
---
## Package Development
### Project Requirements
- [Python](https://www.python.org/) 3.11.*
- [Docker](https://www.docker.com/).
- [Docker Compose](https://docs.docker.com/compose/install/).
- [Poetry](https://python-poetry.org/) for Python package and environment management.
### Installing Dependencies
The Celerity project manages Python package dependencies using [Poetry](https://python-poetry.org/). You'll need to follow the instructions for installation there.
Then you can start a shell session with the new environment with:
```console
$ poetry shell
```
**N.B.** For development with vscode you will need to run the following command:
```console
$ poetry config virtualenvs.in-project true
```
This will installed the poetry `.venv` in the root of the project and allow vscode to setup the environment correctly for development.
To start development, install all of the dependencies as:
```console
$ poetry install
```
**N.B.** _Ensure that any dependency changes are committed to source control, so everyone has a consistenct package dependecy list._
### Local Development
The Celerity development stack can be built with the following `docker` `compose` command, with the `$INSTALL_DEV` build environment argument\*.
```console
$ docker compose -f local.yml build --build-arg INSTALL_DEV="true"
```
\* _This is required to install the development dependencies in the container._
Then start the development stack with a running shell session with:
```console
$ docker compose -f local.yml run app bash
```
**N.B.** _The `docker compose` command will build the development stack if it has not been built already._
### Running Tests
To run the tests, please ensure you have followed the steps for building the development server:
The Celerity development stack can be built with the following `docker` `compose` command, with the `$INSTALL_DEV` build environment argument\*.
```console
$ docker compose -f local.yml build --build-arg INSTALL_DEV="true"
```
You can then run the pytest suite using the following command:
```
$ docker compose -f local.yml exec api pytest
```
Raw data
{
"_id": null,
"home_page": "https://github.com/michaelroberts/celerity",
"name": "celerity",
"maintainer": "Michael J. Roberts",
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": "michael@observerly.com",
"keywords": "astronomy, astrometry, ephemeris",
"author": "Michael J. Roberts",
"author_email": "michael@observerly.com",
"download_url": "https://files.pythonhosted.org/packages/f7/e3/8b75b4466d2ec5f2e055c68d4777daa877738b07d51cc12728d0dfc1e7d7/celerity-0.26.0.tar.gz",
"platform": null,
"description": "[](https://celerity.observerly.com)\n\nCelerity is a lightweight, research-grade, zero-dependency type-safe Python library for astronomical calculations to plan your observations. It's only dependency is the Python 3.11+ standard library.\n\nIt has been designed to be independent of any other popular astronomical libraries, with a focus on providing a simple and intuitive API for performing common astronomical calculations.\n\n**N.B.** _This project is currently in the early stages of development and is not yet ready for production use._\n\n---\n\n## Usage\n\n### Installation\n\nCelerity can be installed using `pip`:\n\n```console\npip install celerity\n```\n\n or `poetry`:\n\n```console\npoetry add celerity\n```\n\n### API\n\nThe API has been designed to be written in an idiomatic and natural way for English speakers, as well as idiomatic to Python. \n\nIt has been specifically designed to only depend on the core set of Python modules, such that it is not strictly dependent on other popular astronomical libraries, e.g., astropy (although it can compliment the usage of these libraries).\n\nIt's important to note that the API does not perform string parsing of times and coordinates, but instead requires the user to provide the correct data types. This is to ensure that the API is type-safe and that the user is aware of the data types being used at all times.\n\nFor example, to find out the horizontal coordinate for the star Betelgeuse on the 14th May 2021 at 12:00 UTC, at Mauna Kea, Hawaii, you would write:\n\n```python\nfrom datetime import datetime, timezone\n\nfrom celerity import Observer, Time\n\n# Mauna Kea, Hawaii:\nobserver = Observer(\n latitude=19.82,\n longitude=-155.47,\n elevation=4205,\n)\n\n# Time of observation in UTC:\ntime = Time(\n when=datetime(2021, 5, 14, 12, 0, 0, tzinfo=timezone.utc)\n)\n\n# Provide an equatorial target in equatorial coordinates at epoch J2000 in units of degrees:\nbetelgeuse = { ra: 88.792938, dec: 7.407064 }\n\n# Observe the target:\nbetelgeuse = observer.at(time).observe({ ra: 88.792938, dec: 7.407064 })\n\n# Get the horizontal coordinates:\n{ alt, az } = betelgeuse.altAz()\n\n# What is the Local Sidereal Time at the time of observation?\nlst = observer.at(time).LST()\n\n# What is the Julian Date at the time of observation?\njd = observer.at(time).JD()\n```\n\n### Notes & Caveats\n\nCelerity is designed such that fundamental SI units of measurement are used, e.g., degrees, metres, seconds, etc. This is to ensure that the API is as accurate as possible, and that the user is aware of the units being used at all times.\n\nThe `Observer` class requires the user to provide the latitude and longitude in degrees, and the elevation in metres. Latitude is positive for the northern hemisphere, and negative for the southern hemisphere between -90\u00b0 at the southern pole and +90\u00b0 at the northern pole. Longitude is always positive for the eastern hemisphere (east of the Prime Meridian), and negative for the western hemisphere (west of the Prime Meridian) representing a longitude between -180\u00b0 and +180\u00b0.\n\nThe `Time` class requires the user to provide the time in UTC, and not in any other timezone. The user can, once the `Time` object has been created, convert the time to any other timezone using the provided class methods.\n\nThe `Target` class requires the user to provide the right ascension and declination in degrees (and not in hours and degrees).\n\n---\n\n## Package Development\n\n### Project Requirements\n\n- [Python](https://www.python.org/) 3.11.*\n- [Docker](https://www.docker.com/).\n- [Docker Compose](https://docs.docker.com/compose/install/).\n- [Poetry](https://python-poetry.org/) for Python package and environment management.\n\n### Installing Dependencies\n\nThe Celerity project manages Python package dependencies using [Poetry](https://python-poetry.org/). You'll need to follow the instructions for installation there.\n\nThen you can start a shell session with the new environment with:\n\n```console\n$ poetry shell\n```\n\n**N.B.** For development with vscode you will need to run the following command:\n\n```console\n$ poetry config virtualenvs.in-project true\n```\n\nThis will installed the poetry `.venv` in the root of the project and allow vscode to setup the environment correctly for development.\n\nTo start development, install all of the dependencies as:\n\n```console\n$ poetry install\n```\n\n**N.B.** _Ensure that any dependency changes are committed to source control, so everyone has a consistenct package dependecy list._\n\n### Local Development\n\nThe Celerity development stack can be built with the following `docker` `compose` command, with the `$INSTALL_DEV` build environment argument\\*.\n\n```console\n$ docker compose -f local.yml build --build-arg INSTALL_DEV=\"true\"\n```\n\n\\* _This is required to install the development dependencies in the container._\n\nThen start the development stack with a running shell session with:\n\n```console\n$ docker compose -f local.yml run app bash\n```\n\n**N.B.** _The `docker compose` command will build the development stack if it has not been built already._\n\n### Running Tests\n\nTo run the tests, please ensure you have followed the steps for building the development server:\n\nThe Celerity development stack can be built with the following `docker` `compose` command, with the `$INSTALL_DEV` build environment argument\\*.\n\n```console\n$ docker compose -f local.yml build --build-arg INSTALL_DEV=\"true\"\n```\n\nYou can then run the pytest suite using the following command:\n\n```\n$ docker compose -f local.yml exec api pytest\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Celerity is a lightweight, zero-dependency and type-safe Python library for astronomical calculations.",
"version": "0.26.0",
"project_urls": {
"Homepage": "https://github.com/michaelroberts/celerity",
"Repository": "https://github.com/michaelroberts/celerity"
},
"split_keywords": [
"astronomy",
" astrometry",
" ephemeris"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "72c2f5c1473710cbaaad5b08b9c9449d85cf983a1f63724b57f9e1e621d39a1d",
"md5": "9670f2673930665ffa2fcfe9ad234507",
"sha256": "994f462d42f9ca12cc4de0636225ddffc30b881491e368b80b3dcc09ffa57a63"
},
"downloads": -1,
"filename": "celerity-0.26.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9670f2673930665ffa2fcfe9ad234507",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 28644,
"upload_time": "2024-04-28T19:57:47",
"upload_time_iso_8601": "2024-04-28T19:57:47.668128Z",
"url": "https://files.pythonhosted.org/packages/72/c2/f5c1473710cbaaad5b08b9c9449d85cf983a1f63724b57f9e1e621d39a1d/celerity-0.26.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f7e38b75b4466d2ec5f2e055c68d4777daa877738b07d51cc12728d0dfc1e7d7",
"md5": "42e26ae725c51354d506f792296011cf",
"sha256": "277471d96c8997ec76d36e685fe1a2ba8f5a9863ebf0716b2d0a42ec6318fb6b"
},
"downloads": -1,
"filename": "celerity-0.26.0.tar.gz",
"has_sig": false,
"md5_digest": "42e26ae725c51354d506f792296011cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 21737,
"upload_time": "2024-04-28T19:57:49",
"upload_time_iso_8601": "2024-04-28T19:57:49.465340Z",
"url": "https://files.pythonhosted.org/packages/f7/e3/8b75b4466d2ec5f2e055c68d4777daa877738b07d51cc12728d0dfc1e7d7/celerity-0.26.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-28 19:57:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michaelroberts",
"github_project": "celerity",
"github_not_found": true,
"lcname": "celerity"
}
JSON
