Metadata-Version: 2.1
Name: adam-assist
Version: 0.1.2
Summary: ADAM Core Propagator class using ASSIST
Keywords: astronomy,orbital mechanics,propagation
Author: Kathleen Kiker
Author-Email: Alec Koumjian <akoumjian@gmail.com>
License: GNU GENERAL PUBLIC LICENSE
        Version 3, 29 June 2007
        
        Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
        Everyone is permitted to copy and distribute verbatim copies
        of this license document, but changing it is not allowed.
        
        Preamble
        
        The GNU General Public License is a free, copyleft license for
        software and other kinds of works.
        
        The licenses for most software and other practical works are designed
        to take away your freedom to share and change the works. By contrast,
        the GNU General Public License is intended to guarantee your freedom to
        share and change all versions of a program--to make sure it remains free
        software for all its users. We, the Free Software Foundation, use the
        GNU General Public License for most of our software; it applies also to
        any other work released this way by its authors. You can apply it to
        your programs, too.
        
        When we speak of free software, we are referring to freedom, not
        price. Our General Public Licenses are designed to make sure that you
        have the freedom to distribute copies of free software (and charge for
        them if you wish), that you receive source code or can get it if you
        want it, that you can change the software or use pieces of it in new
        free programs, and that you know you can do these things.
        
        To protect your rights, we need to prevent others from denying you
        these rights or asking you to surrender the rights. Therefore, you have
        certain responsibilities if you distribute copies of the software, or if
        you modify it: responsibilities to respect the freedom of others.
        
        For example, if you distribute copies of such a program, whether
        gratis or for a fee, you must pass on to the recipients the same
        freedoms that you received. You must make sure that they, too, receive
        or can get the source code. And you must show them these terms so they
        know their rights.
        
        Developers that use the GNU GPL protect your rights with two steps:
        (1) assert copyright on the software, and (2) offer you this License
        giving you legal permission to copy, distribute and/or modify it.
        
        For the developers' and authors' protection, the GPL clearly explains
        that there is no warranty for this free software. For both users' and
        authors' sake, the GPL requires that modified versions be marked as
        changed, so that their problems will not be attributed erroneously to
        authors of previous versions.
        
        Some devices are designed to deny users access to install or run
        modified versions of the software inside them, although the manufacturer
        can do so. This is fundamentally incompatible with the aim of
        protecting users' freedom to change the software. The systematic
        pattern of such abuse occurs in the area of products for individuals to
        use, which is precisely where it is most unacceptable. Therefore, we
        have designed this version of the GPL to prohibit the practice for those
        products. If such problems arise substantially in other domains, we
        stand ready to extend this provision to those domains in future versions
        of the GPL, as needed to protect the freedom of users.
        
        Finally, every program is threatened constantly by software patents.
        States should not allow patents to restrict development and use of
        software on general-purpose computers, but in those that do, we wish to
        avoid the special danger that patents applied to a free program could
        make it effectively proprietary. To prevent this, the GPL assures that
        patents cannot be used to render the program non-free.
        
        The precise terms and conditions for copying, distribution and
        modification follow.
        
        TERMS AND CONDITIONS
        
        0. Definitions.
        
        "This License" refers to version 3 of the GNU General Public License.
        
        "Copyright" also means copyright-like laws that apply to other kinds of
        works, such as semiconductor masks.
        
        "The Program" refers to any copyrightable work licensed under this
        License. Each licensee is addressed as "you". "Licensees" and
        "recipients" may be individuals or organizations.
        
        To "modify" a work means to copy from or adapt all or part of the work
        in a fashion requiring copyright permission, other than the making of an
        exact copy. The resulting work is called a "modified version" of the
        earlier work or a work "based on" the earlier work.
        
        A "covered work" means either the unmodified Program or a work based
        on the Program.
        
        To "propagate" a work means to do anything with it that, without
        permission, would make you directly or secondarily liable for
        infringement under applicable copyright law, except executing it on a
        computer or modifying a private copy. Propagation includes copying,
        distribution (with or without modification), making available to the
        public, and in some countries other activities as well.
        
        To "convey" a work means any kind of propagation that enables other
        parties to make or receive copies. Mere interaction with a user through
        a computer network, with no transfer of a copy, is not conveying.
        
        An interactive user interface displays "Appropriate Legal Notices"
        to the extent that it includes a convenient and prominently visible
        feature that (1) displays an appropriate copyright notice, and (2)
        tells the user that there is no warranty for the work (except to the
        extent that warranties are provided), that licensees may convey the
        work under this License, and how to view a copy of this License. If
        the interface presents a list of user commands or options, such as a
        menu, a prominent item in the list meets this criterion.
        
        1. Source Code.
        
        The "source code" for a work means the preferred form of the work
        for making modifications to it. "Object code" means any non-source
        form of a work.
        
        A "Standard Interface" means an interface that either is an official
        standard defined by a recognized standards body, or, in the case of
        interfaces specified for a particular programming language, one that
        is widely used among developers working in that language.
        
        The "System Libraries" of an executable work include anything, other
        than the work as a whole, that (a) is included in the normal form of
        packaging a Major Component, but which is not part of that Major
        Component, and (b) serves only to enable use of the work with that
        Major Component, or to implement a Standard Interface for which an
        implementation is available to the public in source code form. A
        "Major Component", in this context, means a major essential component
        (kernel, window system, and so on) of the specific operating system
        (if any) on which the executable work runs, or a compiler used to
        produce the work, or an object code interpreter used to run it.
        
        The "Corresponding Source" for a work in object code form means all
        the source code needed to generate, install, and (for an executable
        work) run the object code and to modify the work, including scripts to
        control those activities. However, it does not include the work's
        System Libraries, or general-purpose tools or generally available free
        programs which are used unmodified in performing those activities but
        which are not part of the work. For example, Corresponding Source
        includes interface definition files associated with source files for
        the work, and the source code for shared libraries and dynamically
        linked subprograms that the work is specifically designed to require,
        such as by intimate data communication or control flow between those
        subprograms and other parts of the work.
        
        The Corresponding Source need not include anything that users
        can regenerate automatically from other parts of the Corresponding
        Source.
        
        The Corresponding Source for a work in source code form is that
        same work.
        
        2. Basic Permissions.
        
        All rights granted under this License are granted for the term of
        copyright on the Program, and are irrevocable provided the stated
        conditions are met. This License explicitly affirms your unlimited
        permission to run the unmodified Program. The output from running a
        covered work is covered by this License only if the output, given its
        content, constitutes a covered work. This License acknowledges your
        rights of fair use or other equivalent, as provided by copyright law.
        
        You may make, run and propagate covered works that you do not
        convey, without conditions so long as your license otherwise remains
        in force. You may convey covered works to others for the sole purpose
        of having them make modifications exclusively for you, or provide you
        with facilities for running those works, provided that you comply with
        the terms of this License in conveying all material for which you do
        not control copyright. Those thus making or running the covered works
        for you must do so exclusively on your behalf, under your direction
        and control, on terms that prohibit them from making any copies of
        your copyrighted material outside their relationship with you.
        
        Conveying under any other circumstances is permitted solely under
        the conditions stated below. Sublicensing is not allowed; section 10
        makes it unnecessary.
        
        3. Protecting Users' Legal Rights From Anti-Circumvention Law.
        
        No covered work shall be deemed part of an effective technological
        measure under any applicable law fulfilling obligations under article
        11 of the WIPO copyright treaty adopted on 20 December 1996, or
        similar laws prohibiting or restricting circumvention of such
        measures.
        
        When you convey a covered work, you waive any legal power to forbid
        circumvention of technological measures to the extent such circumvention
        is effected by exercising rights under this License with respect to
        the covered work, and you disclaim any intention to limit operation or
        modification of the work as a means of enforcing, against the work's
        users, your or third parties' legal rights to forbid circumvention of
        technological measures.
        
        4. Conveying Verbatim Copies.
        
        You may convey verbatim copies of the Program's source
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Project-URL: Documentation, https://github.com/unknown/adam-assist#readme
Project-URL: Issues, https://github.com/unknown/adam-assist/issues
Project-URL: Source, https://github.com/unknown/adam-assist
Requires-Python: <4.0,>=3.11
Requires-Dist: adam-core>=0.2.3
Requires-Dist: assist
Requires-Dist: naif-de440
Requires-Dist: numpy
Requires-Dist: ray
Requires-Dist: spiceypy>=6.0.0
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pdm; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Provides-Extra: dev
Description-Content-Type: text/markdown

# adam-assist

[![PyPI - Version](https://img.shields.io/pypi/v/adam-assist.svg)](https://pypi.org/project/adam-assist)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/adam-assist.svg)](https://pypi.org/project/adam-assist)

-----

**Table of Contents**


- [Installation](#installation)
- [Usage](#usage)
  - [Propagating Orbits](#propagating-orbits)
  - [Generating Ephemerides](#generating-ephemerides)


## Overview
`adam-assist` is a pluggable propagator class for the `adam-core` package that uses [ASSIST](https://github.com/matthewholman/assist) for propagating orbits.


## Installation

```console
pip install adam-assist
```

You will need to download the JPL ephemeris files. It is recommended to use the built in utility for this.

```python
from adam_core.propagator.adam_assist import download_jpl_ephemeris_files

download_jpl_ephemeris_files()
```

## Usage

### Propagating Orbits

Here we initialize a set of `adam_core.orbit.Orbit` objects from the JPL Small Bodies Database and propagate them using the `AdamAssistPropagator` class. You can manually initialize the orbits as well.

```python
from adam_core.orbits.query.sbdb import query_sbdb
from adam_core.time import Timestamp
from adam_core.propagator.adam_assist import ASSISTPropagator

# Query the JPL Small Bodies Database for a set of orbits
sbdb_orbits = query_sbdb(["2020 AV2", "A919 FB", "1993 SB"])
times = Timestamp.from_mjd([60000, 60365, 60730], scale="tdb")


propagator = ASSISTPropagator()

propagated = propagator.propagate_orbits(sbdb_orbits, times)
```

Of course you can define your own orbits as well.

```python
import pyarrow as pa
from adam_core.orbits import Orbit
from adam_core.coordinates import CartesianCoordinates, Origin
from adam_core.time import Timestamp
from adam_core.propagator.adam_assist import ASSISTPropagator

# Define an orbit
orbits = Orbit.from_kwargs(
  orbit_id=["1", "2", "3"],
  coordinates=CartesianCoordinates.from_kwargs(
    # use realistic cartesian coords in AU and AU/day
    x=[-1.0, 0.0, 1.0],
    y=[-1.0, 0.0, 1.0],
    z=[-1.0, 0.0, 1.0],
    vx=[-0.1, 0.0, 0.1],
    vy=[-0.1, 0.0, 0.1],
    vz=[-0.1, 0.0, 0.1],
    time=Timestamp.from_mjd([60000, 60365, 60730], scale="tdb"),
    origin=Origin.from_kwargs(code=pa.repeat("SUN", 3)),
    frame="eliptic"
  ),
)

propagator = ASSISTPropagator()

propagated = propagator.propagate_orbits(orbits)
```

### Generating Ephemerides

The `ASSISTPropagator` class uses the `adam-core` default ephemeris generator to generate ephemerides from the `ASSIST` propagated orbits. The default ephemeris generator accounts for light travel time and aberration. See `adam_core.propagator.propagator.EphemerisMixin` for implementation details.


```python
from adam_core.orbits.query.sbdb import query_sbdb
from adam_core.time import Timestamp
from adam_core.observers import Observers
from adam_core.propagator.adam_assist import ASSISTPropagator

# Query the JPL Small Bodies Database for a set of orbits
sbdb_orbits = query_sbdb(["2020 AV2", "A919 FB", "1993 SB"])
times = Timestamp.from_mjd([60000, 60365, 60730], scale="utc")
observers = Observers.from_code("399", times)
propagator = ASSISTPropagator()

ephemerides = propagator.generate_ephemeris(sbdb_orbits, observers)
```






