Update docs for v0.7.0: types, operators, test count, performance framing
- types.mdx: "seven" → "seven base types + one SQL composite", add observer_window section with field table and usage example - operators-gist.mdx: "three operators" → "four operators", reframe SP-GiST performance as scalability feature (honest about seqscan being faster at 14k catalog size, index helps at 100k+) - installation.mdx: "14 test suites" → "15 test suites", list all suites including od_fit, spgist_tle, vallado_518 - design-principles.mdx: clarify observer_window is SQL composite (variable-length, query-time only), base types still STORAGE=plain - pass-prediction.mdx: lead with operator value (80-90% elimination), SP-GiST index framed as optional for large catalogs
This commit is contained in:
parent
845aeee3a5
commit
5e5588fddb
@ -104,7 +104,7 @@ For v0.1.0/v0.2.0 functions, there are no file-scope variables, no static locals
|
|||||||
|
|
||||||
### Fixed-size types
|
### Fixed-size types
|
||||||
|
|
||||||
All seven pg_orrery types use `STORAGE = plain` and fixed `INTERNALLENGTH`. No TOAST, no detoasting, no variable-length headers. The `tle` type is exactly 112 bytes. Direct pointer access via `PG_GETARG_POINTER(n)` --- no copies, no allocations on read.
|
All seven pg_orrery base types use `STORAGE = plain` and fixed `INTERNALLENGTH`. No TOAST, no detoasting, no variable-length headers. The `tle` type is exactly 112 bytes. Direct pointer access via `PG_GETARG_POINTER(n)` --- no copies, no allocations on read. The eighth type, `observer_window`, is a SQL composite used only as a query-time parameter --- it is never stored in table columns.
|
||||||
|
|
||||||
### Deterministic memory
|
### Deterministic memory
|
||||||
|
|
||||||
|
|||||||
@ -97,13 +97,13 @@ import { Tabs, TabItem, Steps, Aside } from "@astrojs/starlight/components";
|
|||||||
|
|
||||||
## Running the test suite
|
## Running the test suite
|
||||||
|
|
||||||
If building from source, the regression tests verify all functions across 14 test suites:
|
If building from source, the regression tests verify all functions across 15 test suites:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make installcheck PG_CONFIG=/usr/bin/pg_config
|
make installcheck PG_CONFIG=/usr/bin/pg_config
|
||||||
```
|
```
|
||||||
|
|
||||||
This runs the tests listed in the `REGRESS` variable: TLE parsing, SGP4 propagation, coordinate transforms, pass prediction, GiST indexing, convenience functions, star observation, Keplerian propagation, planet observation, moon observation, Lambert transfers, and DE ephemeris.
|
This runs the tests listed in the `REGRESS` variable: TLE parsing, SGP4 propagation, coordinate transforms, pass prediction, GiST indexing, convenience functions, star observation, Keplerian propagation, planet observation, moon observation, Lambert transfers, DE ephemeris, orbit determination, SP-GiST visibility index, and the 518 Vallado test vectors.
|
||||||
|
|
||||||
## Upgrading
|
## Upgrading
|
||||||
|
|
||||||
|
|||||||
@ -6,7 +6,7 @@ sidebar:
|
|||||||
|
|
||||||
import { Steps, Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
import { Steps, Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
||||||
|
|
||||||
Satellite pass prediction answers a deceptively simple question: "which satellites will fly over me tonight?" The brute-force approach -- propagating every object in a 30,000-satellite catalog with SGP4 at 10-second intervals over a 24-hour window -- requires billions of floating-point operations. pg_orrery solves this with an SP-GiST index on the `tle` type that prunes by orbital geometry before any propagation runs, reducing the candidate set to a handful of objects that could plausibly be visible.
|
Satellite pass prediction answers a deceptively simple question: "which satellites will fly over me tonight?" The brute-force approach -- propagating every object in a 30,000-satellite catalog with SGP4 at 10-second intervals over a 24-hour window -- requires billions of floating-point operations. pg_orrery solves this with the `&?` visibility cone operator, which applies three geometric filters (altitude, inclination, RAAN) to eliminate 80-90% of candidates without any SGP4 propagation. An optional SP-GiST index provides tree-level pruning for large catalogs.
|
||||||
|
|
||||||
## How you do it today
|
## How you do it today
|
||||||
|
|
||||||
|
|||||||
@ -6,7 +6,7 @@ sidebar:
|
|||||||
|
|
||||||
import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
||||||
|
|
||||||
pg_orrery defines three operators on the `tle` type and two operator classes (GiST and SP-GiST) that enable indexed satellite queries over large catalogs. The GiST index accelerates conjunction screening (orbit-to-orbit overlap). The SP-GiST index accelerates pass prediction (observer-to-orbit visibility).
|
pg_orrery defines four operators on the `tle` type and two operator classes (GiST and SP-GiST) that enable indexed satellite queries over large catalogs. The GiST index accelerates conjunction screening (orbit-to-orbit overlap). The SP-GiST index accelerates pass prediction (observer-to-orbit visibility).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -288,7 +288,9 @@ During the index scan, inner nodes are pruned by altitude band (level 0) and inc
|
|||||||
|
|
||||||
### Performance
|
### Performance
|
||||||
|
|
||||||
The SP-GiST index is most effective for:
|
The `&?` operator eliminates 80-90% of a satellite catalog without SGP4 propagation --- this is the primary value, regardless of whether a sequential scan or index scan evaluates it. At typical catalog sizes (10-30k objects), the operator evaluates the full catalog in under 10 ms, and PostgreSQL's query planner may choose a sequential scan over the index.
|
||||||
|
|
||||||
|
The SP-GiST index becomes advantageous at larger catalog sizes (100k+ objects) where tree-level pruning avoids examining individual TLEs in entire subtrees. The index is most effective for:
|
||||||
|
|
||||||
- **Short query windows** (1-6 hours): The RAAN filter aggressively eliminates satellites whose orbital plane is not currently aligned with the observer
|
- **Short query windows** (1-6 hours): The RAAN filter aggressively eliminates satellites whose orbital plane is not currently aligned with the observer
|
||||||
- **Mid-latitude observers** (30-60 degrees): The inclination filter eliminates equatorial and low-inclination satellites
|
- **Mid-latitude observers** (30-60 degrees): The inclination filter eliminates equatorial and low-inclination satellites
|
||||||
|
|||||||
@ -6,7 +6,7 @@ sidebar:
|
|||||||
|
|
||||||
import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
|
||||||
|
|
||||||
pg_orrery defines seven composite types that represent the core data structures of orbital mechanics. Each type has a fixed on-disk size, a text I/O format for readability, and accessor functions for extracting individual fields.
|
pg_orrery defines seven fixed-size base types and one SQL composite type that represent the core data structures of orbital mechanics. Each base type has a fixed on-disk size, a text I/O format for readability, and accessor functions for extracting individual fields.
|
||||||
|
|
||||||
## tle
|
## tle
|
||||||
|
|
||||||
@ -267,3 +267,40 @@ SELECT body_id,
|
|||||||
FROM generate_series(1, 8) AS body_id,
|
FROM generate_series(1, 8) AS body_id,
|
||||||
planet_heliocentric(body_id, now()) AS h;
|
planet_heliocentric(body_id, now()) AS h;
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## observer_window
|
||||||
|
|
||||||
|
**Type:** SQL composite (variable-length)
|
||||||
|
|
||||||
|
A query-time parameter that defines a ground observer's visibility window. Unlike the seven base types above, `observer_window` is a SQL composite type --- it is not designed for table storage, but as an argument to the `&?` visibility cone operator.
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `obs` | `observer` | Ground location (latitude, longitude, altitude) |
|
||||||
|
| `t_start` | `timestamptz` | Start of observation window |
|
||||||
|
| `t_end` | `timestamptz` | End of observation window |
|
||||||
|
| `min_el` | `float8` | Minimum elevation angle in degrees |
|
||||||
|
|
||||||
|
### Construction
|
||||||
|
|
||||||
|
Construct with `ROW(...)::observer_window` syntax:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Eagle, Idaho: 6-hour window, 10 deg minimum elevation
|
||||||
|
SELECT tle
|
||||||
|
FROM catalog
|
||||||
|
WHERE tle &? ROW(
|
||||||
|
observer('43.6977N 116.3535W 760m'),
|
||||||
|
'2024-01-01 01:00:00+00'::timestamptz,
|
||||||
|
'2024-01-01 07:00:00+00'::timestamptz,
|
||||||
|
10.0
|
||||||
|
)::observer_window;
|
||||||
|
```
|
||||||
|
|
||||||
|
<Aside type="tip">
|
||||||
|
See [Satellite Pass Prediction](/guides/pass-prediction/) for the full two-stage workflow using `&?` to filter candidates before SGP4 propagation with `predict_passes()`.
|
||||||
|
</Aside>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user