{"id":15735309,"url":"https://github.com/open-space-collective/open-space-toolkit-physics","last_synced_at":"2026-02-26T02:22:36.270Z","repository":{"id":33011166,"uuid":"136835583","full_name":"open-space-collective/open-space-toolkit-physics","owner":"open-space-collective","description":"Physical units, time, reference frames, environment modeling.","archived":false,"fork":false,"pushed_at":"2025-03-11T18:43:28.000Z","size":123406,"stargazers_count":26,"open_issues_count":9,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T15:08:23.747Z","etag":null,"topics":["atmospheric","coordinates","cpp","engineering","ephemeris","gravity","magnetic","physics","python","space","stars","time","toolkit"],"latest_commit_sha":null,"homepage":"https://open-space-collective.github.io/open-space-toolkit-physics/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-space-collective.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-10T18:44:58.000Z","updated_at":"2025-03-11T06:44:22.000Z","dependencies_parsed_at":"2024-02-19T10:44:31.253Z","dependency_job_id":"e683c7f5-d3fb-4b82-893d-83c409bcb4e2","html_url":"https://github.com/open-space-collective/open-space-toolkit-physics","commit_stats":{"total_commits":479,"total_committers":15,"mean_commits":"31.933333333333334","dds":"0.40918580375782876","last_synced_commit":"c69607f3703842cb2673a60956c6a7881c0e0ad4"},"previous_names":[],"tags_count":122,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-space-collective%2Fopen-space-toolkit-physics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-space-collective%2Fopen-space-toolkit-physics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-space-collective%2Fopen-space-toolkit-physics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-space-collective%2Fopen-space-toolkit-physics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-space-collective","download_url":"https://codeload.github.com/open-space-collective/open-space-toolkit-physics/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509221,"owners_count":20950232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atmospheric","coordinates","cpp","engineering","ephemeris","gravity","magnetic","physics","python","space","stars","time","toolkit"],"created_at":"2024-10-04T01:12:13.088Z","updated_at":"2026-02-26T02:22:36.263Z","avatar_url":"https://github.com/open-space-collective.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open Space Toolkit ▸ Physics\n\n[![Build and Test](https://github.com/open-space-collective/open-space-toolkit-physics/actions/workflows/build-test.yml/badge.svg?branch=main)](https://github.com/open-space-collective/open-space-toolkit-physics/actions/workflows/build-test.yml)\n[![Release](https://github.com/open-space-collective/open-space-toolkit-physics/actions/workflows/release.yml/badge.svg)](https://github.com/open-space-collective/open-space-toolkit-physics/actions/workflows/release.yml)\n[![Code Coverage](https://codecov.io/gh/open-space-collective/open-space-toolkit-physics/branch/main/graph/badge.svg)](https://codecov.io/gh/open-space-collective/open-space-toolkit-physics)\n[![Documentation](https://img.shields.io/readthedocs/pip/stable.svg)](https://open-space-collective.github.io/open-space-toolkit-physics)\n[![GitHub version](https://badge.fury.io/gh/open-space-collective%2Fopen-space-toolkit-physics.svg)](https://badge.fury.io/gh/open-space-collective%2Fopen-space-toolkit-physics)\n[![PyPI version](https://badge.fury.io/py/open-space-toolkit-physics.svg)](https://badge.fury.io/py/open-space-toolkit-physics)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nPhysical units, time, reference frames, environment modeling.\n\n\u003cimg src=\"./docs/assets/gravitational-anomaly.png\" height=\"500px\" width=\"auto\"\u003e\n\n*Gravitational field anomaly between EGM96 and WGS84 models.*\n\n## Getting Started\n\nWant to get started? This is the simplest and quickest way:\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/open-space-collective/open-space-toolkit/main?urlpath=lab/tree/notebooks)\n\n*Nothing to download or install! This will automatically start a [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) environment in your browser with Open Space Toolkit libraries and example notebooks ready to use.*\n\n### Alternatives\n\n#### Docker Images\n\n[Docker](https://www.docker.com/) must be installed on your system.\n\n##### iPython\n\nThe following command will start an [iPython](https://ipython.org/) shell within a container where the OSTk components are already installed:\n\n```bash\ndocker run -it openspacecollective/open-space-toolkit-physics-python\n```\n\nOnce the shell is up and running, playing with it is easy:\n\n```py\nfrom ostk.physics import Environment # Environment modeling class\nfrom ostk.physics.time import Instant # Instant class\nfrom ostk.physics.coordinate import Frame # Reference frame class\n\nenvironment = Environment.default(set_global=True) # Bootstrap a default environment, and set it as the global environment\n\nmoon = environment.access_object_with_name('Moon') # Access Moon\n\ninstant = Instant.now()\n\nmoon.get_position_in(Frame.ITRF(), instant) # Position of the Moon in ITRF\nmoon.get_axes_in(Frame.ITRF(), instant) # Axes of the Moon in ITRF\n```\n\nBy default, OSTk fetches the ephemeris from JPL, Earth Orientation Parameters (EOP) and leap second count from IERS.\n\nAs a result, when running OSTk for the first time, it may take a minute to fetch all the necessary data.\n\n*Tip: Use tab for auto-completion!*\n\n##### JupyterLab\n\nThe following command will start a [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) server within a container where the OSTk components are already installed:\n\n```bash\ndocker run --publish=8888:8888 openspacecollective/open-space-toolkit-physics-jupyter\n```\n\nOnce the container is running, access [http://localhost:8888/lab](http://localhost:8888/lab) and create a Python 3 Notebook.\n\n## Installation\n\n### C++\n\nThe binary packages are hosted using [GitHub Releases](https://github.com/open-space-collective/open-space-toolkit-physics/releases):\n\n- Runtime libraries: `open-space-toolkit-physics-X.Y.Z-1.x86_64-runtime`\n- C++ headers: `open-space-toolkit-physics-X.Y.Z-1.x86_64-devel`\n- Python bindings: `open-space-toolkit-physics-X.Y.Z-1.x86_64-python`\n\n#### Debian / Ubuntu\n\nAfter downloading the relevant `.deb` binary packages, install:\n\n```bash\napt install open-space-toolkit-physics-*.deb\n```\n\n### Python\n\nInstall from [PyPI](https://pypi.org/project/open-space-toolkit-physics/):\n\n```bash\npip install open-space-toolkit-physics\n```\n\n## Documentation\n\nDocumentation is available [here](https://open-space-collective.github.io/open-space-toolkit-physics/):\n\n\u003cdetails\u003e\n\u003csummary\u003eStructure\u003c/summary\u003e\n\u003cp\u003e\n\nThe library exhibits the following structure:\n\n```txt\n├── Unit\n│   ├── Length\n│   ├── Mass\n│   ├── Time\n│   ├── Temperature\n│   ├── Electric Current\n│   ├── Luminous Intensity\n│   └── Derived\n│       ├── Angle\n│       ├── Solid Angle\n│       ├── Frequency\n│       ├── Force\n│       ├── Pressure\n│       ├── Area\n│       ├── Volume\n│       └── Information\n├── Time\n│   ├── Scale (UTC, TT, TAI, UT1, TCG, TCB, TDB, GMST, GPST, GST, GLST, BDT, QZSST, IRNSST)\n│   ├── Instant\n│   ├── Duration\n│   ├── Interval\n│   ├── Date\n│   ├── Time\n│   └── DateTime\n├── Coordinate\n│   ├── Transform\n│   └── Frame (ECI, ECEF, NED, LVLHGD, LVLHGDGT, ...)\n├── Geographic\n│   ├── Position\n│   ├── Area\n│   ├── Volume\n│   ├── Coordinate Reference System (CRS)\n│   └── Universal Transverse Mercator (UTM)\n└── Environment\n    ├── Constant\n    ├── Object\n    │   └── Celestial\n    ├── Ephemeris\n    │   ├── Analytical\n    │   ├── Tabulated\n    │   └── SPICE (JPL)\n    ├── Gravity\n    │   ├── Barycentric\n    │   ├── Earth Gravitational Model 1996 (EGM96)\n    │   └── Earth Gravitational Model 2008 (EGM2008)\n    ├── Atmospheric\n    │   ├── Exponential\n    │   └── NRLMSISE00\n    └── Magnetic\n        ├── Dipole\n        ├── World Magnetic Model 2010 (WMM2010)\n        ├── World Magnetic Model 2015 (WMM2015)\n        ├── Enhanced Magnetic Model 2010 (EMM2010)\n        ├── Enhanced Magnetic Model 2015 (EMM2015)\n        ├── International Geomagnetic Reference Field 11 (IGRF11)\n        └── International Geomagnetic Reference Field 12 (IGRF12)\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n## Data Management\n\nOSTk Physics uses input data from various sources to determine the state of the space environment at any given time. The following input data is used:\n\n- IERS Reference Frame Data\n- CSSI Solar Flux/Space Weather Data\n- Gravitational Survey Data\n- Magnetic Survey Data\n- SPICE Kernels\n\nNone of these files are shipped with the source code of this library. OSTk Physics has the capability to fetch the required files at runtime if they are not present or if they are outdated. This is done using file Manager classes (see any file named `Manager.hpp`). Data for any use-case is queried through the Manager class rather than directly, which allows the Manager to handle file loading and fetching.\nThe managers have two modes, which can be configured via environment variables (explained below).\n- `Automatic`: Will load the data from the provided directories, if the data does not exist it will be fetched.\n- `Manual`: Will load the data from the provided directories, if the data does not exist it will raise an error.\n\nIf you would like to seed the ostk data generation so that you already have an initial copy of all the data files (to avoid a large initial fetch at runtime), then we recommend running the following commands to set up your environment.\n```\n# Set the environment variable for OSTk Data location\nexport OSTK_DATA_LOCAL_CACHE=/path/to/preferred/data/storage/dir\nexport OSTK_PHYSICS_DATA_LOCAL_REPOSITORY=$OSTK_DATA_LOCAL_CACHE/data\n\n# Clone OSTk data repo into that dir\nRUN git clone --branch v1 --single-branch --depth=1 https://github.com/open-space-collective/open-space-toolkit-data.git $OSTK_DATA_LOCAL_CACHE \u0026\u0026 chmod -R g+w $OSTK_DATA_LOCAL_CACHE\n```\n\nFor users that are installing OSTk into docker images, here is what we recommend you add to your dockerfiles.\n```\nARG OSTK_DATA_LOCAL_CACHE=\"/var/cache/open-space-toolkit-data\"\nENV OSTK_DATA_LOCAL_CACHE=\"${OSTK_DATA_LOCAL_CACHE}\"\nENV OSTK_PHYSICS_DATA_LOCAL_REPOSITORY=\"${OSTK_DATA_LOCAL_CACHE}/data\"\n\nRUN git clone --branch v1 --single-branch --depth=1 https://github.com/open-space-collective/open-space-toolkit-data.git ${OSTK_DATA_LOCAL_CACHE} \u0026\u0026 chmod -R g+w ${OSTK_DATA_LOCAL_CACHE}\n\n# Add the line below if the container's user will not be root\nRUN chown -R ${USER_UID}:${USER_GID} ${OSTK_DATA_LOCAL_CACHE}\n```\nIf you have a multi-stage dockerfile, then you can easily just copy the ostk-data repo install from one build stage (in the example below that's `build-env`) to the next, so that you don't have to reinstall it on every build stage.\n```\n# If you are copying to an image where the user is currently root\nCOPY --from=build-env ${OSTK_DATA_LOCAL_CACHE} ${OSTK_DATA_LOCAL_CACHE}\n# Or if you are copying to an image where the user is not currently root\nCOPY --from=build-env --chown=${USER_UID}:${USER_GID} ${OSTK_DATA_LOCAL_CACHE} ${OSTK_DATA_LOCAL_CACHE}\n```\n\nThe following table shows the availabe data source settings with the different environment variables you can set:\n\n| Environment Variable                                                                   | Default Value                                                                                            |\n| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| `OSTK_PHYSICS_DATA_LOCAL_REPOSITORY`                                                 | `./.open-space-toolkit/physics/data` [Bulk setting. Overridden by specific repository settings below.] |\n| `OSTK_PHYSICS_COORDINATE_FRAME_PROVIDER_IERS_MANAGER_MODE`                           | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_COORDINATE_FRAME_PROVIDER_IERS_MANAGER_LOCAL_REPOSITORY`               | `./.open-space-toolkit/physics/data/coordinate/frame/provider/iers`                                    |\n| `OSTK_PHYSICS_COORDINATE_FRAME_PROVIDER_IERS_MANAGER_LOCAL_REPOSITORY_LOCK_TIMEOUT`  | `60`                                                                                                   |\n| `OSTK_PHYSICS_ENVIRONMENT_EPHEMERIS_SPICE_ENGINE_MODE`                               | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_ENVIRONMENT_EPHEMERIS_SPICE_MANAGER_LOCAL_REPOSITORY`                  | `./.open-space-toolkit/physics/data/environment/ephemeris/spice`                                       |\n| `OSTK_PHYSICS_ENVIRONMENT_EPHEMERIS_SPICE_MANAGER_LOCAL_REPOSITORY_LOCK_TIMEOUT`     | `60`                                                                                                   |\n| `OSTK_PHYSICS_ENVIRONMENT_GRAVITATIONAL_EARTH_MANAGER_MODE`                          | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_ENVIRONMENT_GRAVITATIONAL_EARTH_MANAGER_LOCAL_REPOSITORY`              | `./.open-space-toolkit/physics/data/environment/gravitational/earth`                                   |\n| `OSTK_PHYSICS_ENVIRONMENT_GRAVITATIONAL_EARTH_MANAGER_LOCAL_REPOSITORY_LOCK_TIMEOUT` | `60`                                                                                                   |\n| `OSTK_PHYSICS_ENVIRONMENT_MAGNETIC_EARTH_MANAGER_MODE`                               | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_ENVIRONMENT_MAGNETIC_EARTH_MANAGER_LOCAL_REPOSITORY`                   | `./.open-space-toolkit/physics/data/environment/magnetic/earth`                                        |\n| `OSTK_PHYSICS_ENVIRONMENT_MAGNETIC_EARTH_MANAGER_LOCAL_REPOSITORY_LOCK_TIMEOUT`      | `60`                                                                                                   |\n| `OSTK_PHYSICS_ENVIRONMENT_ATMOSPHERIC_EARTH_MANAGER_MODE`                            | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_ENVIRONMENT_ATMOSPHERIC_EARTH_MANAGER_LOCAL_REPOSITORY`                | `./.open-space-toolkit/physics/data/environment/atmospheric/earth`                                     |\n| `OSTK_PHYSICS_ENVIRONMENT_ATMOSPHERIC_EARTH_MANAGER_LOCAL_REPOSITORY_LOCK_TIMEOUT`   | `60`                                                                                                   |\n| `OSTK_PHYSICS_DATA_REMOTE_URL`                                                       | `https://github.com/open-space-collective/open-space-toolkit-data/raw/v1/data/`                        |\n| `OSTK_PHYSICS_DATA_MANIFEST_MANAGER_MODE`                                            | `Automatic`                                                                                            |\n| `OSTK_PHYSICS_DATA_MANIFEST_LOCAL_REPOSITORY`                                        | `./.open-space-toolkit/physics/data/`                                                                  |\n| `OSTK_PHYSICS_DATA_MANIFEST_LOCAL_REPOSITORY_LOCK_TIMEOUT`                           | `60`                                                                                                   |\n| `OSTK_PHYSICS_FRAME_MANAGER_MAX_TRANSFORM_CACHE_SIZE`                                | `1000`                                                                                                 |\n\n## Tutorials\n\nTutorials are available here:\n\n- [C++](./tutorials/cpp)\n- [Python](./tutorials/python)\n\n## Setup\n\n### Development Environment\n\nUsing [Docker](https://www.docker.com) for development is recommended, to simplify the installation of the necessary build tools and dependencies.\nInstructions on how to install Docker are available [here](https://docs.docker.com/install/).\n\nTo start the development environment:\n\n```bash\nmake dev\n```\n\nThis will:\n\n1. Build the `openspacecollective/open-space-toolkit-physics-development` Docker image.\n2. Create a development environment container with local source files and helper scripts mounted.\n3. Start a `bash` shell from the `./build` working directory.\n\nIf installing Docker is not an option, you can manually install the development tools (GCC, CMake) and all required dependencies,\nby following a procedure similar to the one described in the [Development Dockerfile](./docker/development/Dockerfile).\n\n### Build\n\nFrom the `./build` directory:\n\n```bash\ncmake ..\nmake\n```\n\n*Tip: The `ostk-build` command simplifies building from within the development environment.*\n\n### Test\n\nTo start a container to build and run the tests:\n\n```bash\nmake test\n```\n\nOr to run them manually:\n\n```bash\n./bin/open-space-toolkit-physics.test\n```\n\n*Tip: The `ostk-test` command simplifies running tests from within the development environment.*\n\n## Dependencies\n\n| Name          | Version        | License                                                 | Link                                                                                                                                    |\n| ------------- | -------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| Pybind11      | `2.10.1`     | BSD-3-Clause                                            | [github.com/pybind/pybind11](https://github.com/pybind/pybind11)                                                                           |\n| {fmt}         | `5.2.0`      | BSD-2-Clause                                            | [github.com/fmtlib/fmt](https://github.com/fmtlib/fmt)                                                                                     |\n| ordered-map   | `0.6.0`      | MIT                                                     | [github.com/Tessil/ordered-map](https://github.com/Tessil/ordered-map)                                                                     |\n| Eigen         | `3.3.7`      | MPL2                                                    | [eigen.tuxfamily.org](http://eigen.tuxfamily.org/index.php)                                                                                |\n| IAU SOFA      | `2023-10-11` | [SOFA Software License](http://www.iausofa.org/tandc.html) | [www.iausofa.org](http://www.iausofa.org)                                                                                                  |\n| SPICE Toolkit | `N0067`      | [NAIF](https://naif.jpl.nasa.gov/naif/rules.html)          | [naif.jpl.nasa.gov/naif/toolkit.html](https://naif.jpl.nasa.gov/naif/toolkit.html)                                                         |\n| GeographicLib | `1.52`       | MIT                                                     | [geographiclib.sourceforge.io](https://geographiclib.sourceforge.io)                                                                       |\n| Core          | `main`       | Apache License 2.0                                      | [github.com/open-space-collective/open-space-toolkit-core](https://github.com/open-space-collective/open-space-toolkit-core)               |\n| I/O           | `main`       | Apache License 2.0                                      | [github.com/open-space-collective/open-space-toolkit-io](https://github.com/open-space-collective/open-space-toolkit-io)                   |\n| Mathematics   | `main`       | Apache License 2.0                                      | [github.com/open-space-collective/open-space-toolkit-mathematics](https://github.com/open-space-collective/open-space-toolkit-mathematics) |\n\n## Contribution\n\nContributions are more than welcome!\n\nPlease read our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose fixes and improvements, and how to build and test the code.\n\n## Special Thanks\n\n[![Loft Orbital](https://github.com/open-space-collective/open-space-toolkit/blob/main/assets/thanks/loft_orbital.png)](https://www.loftorbital.com/)\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-space-collective%2Fopen-space-toolkit-physics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-space-collective%2Fopen-space-toolkit-physics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-space-collective%2Fopen-space-toolkit-physics/lists"}