Metadata-Version: 2.1
Name: adam-assist
Version: 0.3.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/B612-Asteroid-Institute/adam-assist#readme
Project-URL: Issues, https://github.com/B612-Asteroid-Institute/adam-assist/issues
Project-URL: Source, https://github.com/B612-Asteroid-Institute/adam-assist
Requires-Python: <3.13,>=3.11
Requires-Dist: adam-core>=0.4.0
Requires-Dist: naif-de440
Requires-Dist: jpl-small-bodies-de441-n16
Requires-Dist: assist-adam-fork==1.1.9.post1
Requires-Dist: numpy
Requires-Dist: ray
Requires-Dist: spiceypy>=6.0.0
Requires-Dist: rebound>=4.4.10
Provides-Extra: dev
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"
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
```

## 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_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_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_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)
```

## Configuration

When initializing the `ASSISTPropagator`, you can configure several parameters that control the integration. 
These parameters are passed directly to REBOUND's IAS15 integrator. The IAS15 integrator is a high accuracy integrator that uses adaptive timestepping to maintain precision while optimizing performance.

- `min_dt`: Minimum timestep for the integrator (default: 1e-12 days)
- `initial_dt`: Initial timestep for the integrator (default: 0.001 days)
- `epsilon`: Controls the adaptive timestep behavior (default: 1e-6)
- `adaptive_mode`: Controls the adaptive timestep behavior (default: 1)

These parameters are passed directly to REBOUND's IAS15 integrator. The IAS15 integrator is a high accuracy integrator that uses adaptive timestepping to maintain precision while optimizing performance.

Example:

```python
propagator = ASSISTPropagator(
  min_dt=1e-12,
  initial_dt=0.0001,
  epsilon=1e-6,
  adaptive_mode=1
)
```

When initializing the `ASSISTPropagator`, you can configure several parameters that control the integration. 
These parameters are passed directly to REBOUND's IAS15 integrator. The IAS15 integrator is a high accuracy integrator that uses adaptive timestepping to maintain precision while optimizing performance.

## Default SPK Files

The asteroids SPK file sb441-n16.bsp contains the 16 largest asteroids in the solar system. They are listed here by numberfor reference:

1, 3, 4, 7, 10, 15, 16, 31, 52, 65, 70, 87, 88, 107, 511, 704

