Add our first example notebooks for 2024 YR4 (#144)

examples/2024_yr4_impact_risk.ipynb

@@ -0,0 +1,178 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# So you Want to Calculate an Impact Risk\n",
+    "\n",
+    "Here we walk you through the steps necesssary to calculate the impact risk for a specified orbit, in this case 2024 YR4.\n",
+    "We're going to take a few steps:\n",
+    "\n",
+    "1. Fetch the state vector for 2024 YR4 from JPL Horizons\n",
+    "2. Run calculate impacts, it will create and propagate samples through time and check for collisions.\n",
+    "3. Summarize the results into an impact risk.\n",
+    "\n",
+    "\n",
+    "Before we can start, you will need to install a couple packages.\n",
+    "\n",
+    "```bash\n",
+    "pip install adam-core adam-assist\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "  orbit_id   object_id  coordinates.x  coordinates.y  coordinates.z  \\\n",
+      "0    00000  (2024 YR4)      -0.554305       1.039765      -0.031525   \n",
+      "\n",
+      "   coordinates.vx  coordinates.vy  coordinates.vz  coordinates.time.days  \\\n",
+      "0       -0.019574       -0.000133       -0.001166                  60693   \n",
+      "\n",
+      "   coordinates.time.nanos                      coordinates.covariance.values  \\\n",
+      "0                       0  [2.6790681662875186e-12, -4.746648923989143e-1...   \n",
+      "\n",
+      "  coordinates.origin.code  \n",
+      "0                     SUN  \n"
+     ]
+    }
+   ],
+   "source": [
+    "# Fetch the state vector from Small Bodies Database (SBDB)\n",
+    "from adam_core.orbits.query import query_sbdb\n",
+    "\n",
+    "yr4 = query_sbdb([\"2024 YR4\"])\n",
+    "\n",
+    "print(yr4.to_dataframe())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[\n",
+      "  2925\n",
+      "]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# We need to know how many days out to run the propagation,\n",
+    "# relative to when the orbit state vector is defined.\n",
+    "# Let's go 30 days past the possible 2032 impact of 2024 YR4\n",
+    "from adam_core.time import Timestamp\n",
+    "approx_impact_date = Timestamp.from_iso8601([\"2032-12-22\"], scale=\"tdb\")\n",
+    "thirty_days_after_impact = approx_impact_date.add_days(30)\n",
+    "days_until_thirty_days_after_impact, _ = thirty_days_after_impact.difference(yr4.coordinates.time)\n",
+    "print(days_until_thirty_days_after_impact)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "EarthImpacts(size=19)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Now we initialize our propagator, and pass it to our calculate_impacts function\n",
+    "from adam_core.dynamics.impacts import calculate_impacts\n",
+    "from adam_assist import ASSISTPropagator\n",
+    "\n",
+    "propagator = ASSISTPropagator()\n",
+    "\n",
+    "final_states, earth_impacts = calculate_impacts(\n",
+    "    yr4,\n",
+    "    days_until_thirty_days_after_impact[0].as_py(),\n",
+    "    propagator,\n",
+    "    num_samples=1000,\n",
+    "    processes=10, # Multiprocessing speeds things up if you have the CPUs\n",
+    ")\n",
+    "\n",
+    "print(earth_impacts)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "  orbit_id  impacts  variants  cumulative_probability  mean_impact_time.days  \\\n",
+      "0    00000       19      1000                   0.019                  63588   \n",
+      "\n",
+      "   mean_impact_time.nanos  stddev_impact_time  minimum_impact_time.days  \\\n",
+      "0          50517116965167             0.00501                     63588   \n",
+      "\n",
+      "   minimum_impact_time.nanos  maximum_impact_time.days  \\\n",
+      "0             49983530294895                     63588   \n",
+      "\n",
+      "   maximum_impact_time.nanos  \n",
+      "0             51346236683428  \n"
+     ]
+    }
+   ],
+   "source": [
+    "# Now we can summarize the returns, a simple ratio in our case\n",
+    "# with only 1 orbit considered\n",
+    "from adam_core.dynamics.impacts import calculate_impact_probabilities\n",
+    "ip = calculate_impact_probabilities(final_states, earth_impacts)\n",
+    "print(ip.to_dataframe())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And there you have it. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

pyproject.toml

@@ -72,6 +72,7 @@ test = [
     "black",
     "adam-assist>=0.2.2",
     "ipython>=8.32.0",
+    "ipykernel>=6.29.5",
 ]
 
 [tool.black]