The layer is complete at three hundred and sixty two blocks across the
resource, task, schedule, conflict and scheduler crates, including the
swept search and the improvement pass.
Seventy-five comment blocks across the error kinds, the resource model
and the window algebra. The English is unchanged and the Chinese follows
under a blank doc line, as the glossary sets out.
Three measurements, each answering a different question: what one call
costs, how the cost grows with size, and what the other cores save. The
method states the three rules the tools follow, no warm-up, best of several
runs, and cost per unit rather than an absolute figure, so a reader can
reproduce and judge.
The findings are that the numerical kernels are linear and parallelise
well, a day over two thousand satellites costs 0.7 seconds on one core and
81 milliseconds on sixteen, and that interpolation is about ten times
cheaper than propagation. Two combined operations are limited by their
algorithm: greedy planning is quadratically serial, and the duplicate
check on edge insertion squares that quadratic, so threading helps neither.
Eight threads is recommended, since efficiency falls to about half at
sixteen.
Applies the glossary across apsis-math, apsis-time, apsis-leap,
apsis-coord, apsis-geodesy and the five orbit crates that were already
implemented, plus apsis-ephemeris, apsis-maneuver and apsis-orbit. Five
hundred and seven comment blocks now carry the English paragraph and the
Chinese one.
The checker learned to skip a comment that is only a formula, since a bare
symbol has no prose to translate and repeating it in Chinese would be noise.
The SGP4 cross-check still passes, so nothing in the numerical path moved.
Four of the five physics crates are done, 104 of 239 blocks in the layer.
The remaining one is apsis-frames, which holds the IAU 2000 Earth
orientation models and carries the largest number of formulas.
All 180 comment blocks across apsis-core, apsis-units and apsis-math now
carry both languages. The checker confirms no mangled bytes and no English
word left inside a Chinese sentence, two mistakes that occurred while
writing them and are now caught mechanically.
apsis-units and apsis-core are done, 86 of 180 comment blocks in the
layer. The checker in scripts/check-bilingual.py reports which blocks still
lack Chinese, and also catches the two mistakes that are easy to make while
adding a language: a mangled byte sequence, and an English word left inside
a Chinese sentence, which is what happened once in quantity.rs and is now
caught mechanically.
Translations keep terms that have a standard Chinese name in Chinese and
leave proper nouns, abbreviations and method names in English, as the
glossary sets out. The English text is never reworded.
The comment said the inclination was rounded to one decimal place, but
the format prints it at full precision, so 53.25 degrees came out intact
where the comment promised 53.2. The notation is an identifier, so
truncating it would lose information for nothing.
The first crate of the sweep, so the layout can be checked before the
remaining forty. English paragraph, empty doc line, then the Chinese, per
the glossary. Terms with a standard Chinese name use it directly, so
semi-major axis reads 半长轴 rather than carrying the English each time;
Walker, SGP4 and the frame abbreviations stay as they are.
Every comment block in the crate now has both languages, the Display
strings are untouched because translating them would change what a program
prints, and the three formulas the comments state were checked against the
code: the phase offset is 2 pi f / t, the plane spacing 2 pi / p, and the
anomaly spacing 2 pi / (t / p), all of which match.
The bilingual documentation convention needs a rule for terms, otherwise the
same word gets translated two ways in two files. The glossary separates the
terms that keep their English form, being proper names, abbreviations and
methods that exist only in English in the source literature, from the terms
that have a standard Chinese name and use it directly. It also fixes how a
formula is written, since a formula in a comment has to agree with the code
it describes.
Both languages are written, as the convention requires.
The search binary searches the sample list to interpolate between the two
samples that straddle a crossing, and a binary search over an unordered
list returns a wrong index instead of failing. Only the first and last
times were checked, so a sequence whose ends were in order but whose
middle was not refined each crossing against the wrong pair of positions
and reported a pass that never happened. On a circular ground track,
shuffling two samples changed the result from three passes to two and
still returned Ok.
The whole sequence is now checked, with a new UnorderedSamples error kind
that says which pair is out of order. The test covers the middle-of-
sequence case that the end check missed.
Two comments also described something other than what the code does, and
two Option-returning accessors did not say what makes them None:
- GravityModel::x2o3 is the constant 2/3, used as an exponent in the
mean motion and drag corrections, not 2 * xke^2 as its comment claimed;
the sgp4 reference implementation uses the same constant the same way.
- WalkerPattern::plane_spacing and phase_offset returned None without
saying so, which is the case a caller has to handle.
Both READMEs claimed twelve expect sites where there are thirteen, because
apsis-math/src/parallel.rs added one and the count was not carried over.
The notes were Chinese only, so a reader arriving from GitHub, which
renders README.md by default, met a wall. Each note now follows the
convention the wider ecosystem uses: English in X.md and Simplified
Chinese in X.zh.md, with a switch at the top of both, the way
zeromicro/go-zero and alist-org/alist present theirs.
The Chinese text moved to the .zh.md name rather than being rewritten, so
nothing was lost, and the English is a translation of the same content
rather than a summary of it.
Two figures in the notes had gone stale and are corrected while
translating: there are thirteen expect assertions rather than twelve,
because apsis-math/src/parallel.rs added one, and the table listed eight
of them rather than all. The layer note no longer quotes an edge count,
which changed as the code grew and was already out of date.
The confirmation that follows the sweep called the public feasibility
test, which scans the task list once to collect the boundaries and again,
per boundary, to sum the demand of every covering placement. That is
quadratic per task and dominated the search: removing the confirmation
alone cut the crowded case by eight, which located the cost.
The index built for the sweep is now passed into that test, so both the
boundary collection and the demand sum read a task by its identifier
instead of searching for it. The public entry point keeps its signature
and builds the index for a caller that has none.
Planning three thousand two hundred mutually contending tasks falls from
6.7 seconds to 0.48, and the plans are identical: the check compares the
start time and end of every placement, before and after, across two
resources with disjoint availability windows.
The search listed every time feasibility could change and tested each in
turn, which recomputed the load profile of every resource once per
candidate. The profile does not depend on the candidate, so it is now
swept once: the intervals where a resource has no room are cut from its
availability windows, and the earliest surviving start is read off the
front. The result is confirmed with the direct test and the enumeration is
kept as the fallback, so the sweep is an accelerator and never a second
definition of what is feasible.
The demand of a placed task is read through a vector indexed by task
identifier rather than by scanning the task list or by hashing, because the
identifier is a small dense integer and an array index beats both. Two
thousand random scenarios confirm the two forms agree exactly.
On the crowded case, where every task competes for one resource and the
capacity is the binding constraint, planning three thousand two hundred
tasks falls from 6.7 to 3.7 seconds.
The choice of which loops to thread follows the cost of one item and the
size of the batch, and the note records both ends: the propagation that
gains five fold over a month and barely gains over a day, and the
visibility sweep that is slower in parallel below a few hundred satellites
because a single test costs a few nanoseconds. The interfaces say the same
thing, so a caller knows when to reach for them.
The parallelism note linked to a type the module does not import, which
rustdoc rejects, so it reads as plain text now. The access batch test
computed a propagated state it did not use; it now takes the shell radius
from it so the track sits at a realistic altitude.
A single visibility test costs a few nanoseconds, so the thread start up is
only repaid by a large matrix. Measured on sixteen cores the parallel form
gains from a few hundred satellites and loses below that, so the note says
so and points a small shell at the sequential form.
Building a topology asks the same geometry question for every pair of
satellites, which is a quadratic number of independent tests, and that loop
is the dominant cost of the construction. The parallel form returns the
same row major matrix in the same order as the sequential one.
A ground station's access schedule is one search per satellite, each
independent of the others, and a shell gives enough of them to pay for the
threads. The parallel form returns the same summaries in the same order as
the sequential one, including an error at the position the sequential form
would put it, so one bad track does not hide the rest.
A coverage run wants a satellite's state at every minute of a day, and each
state is independent, so the loop is a candidate for several cores and the
work is large enough to pay for the threads. The parallel form returns the
same values in the same order as the sequential one, including reporting a
decayed instant as None rather than stopping early.
The workspace forbids third party crates, and a thread pool is not needed:
every loop in this workspace that benefits from several cores iterates
independent items, which scoped threads express directly. Borrowing the
data removes the need for an Arc, and joining inside the scope means no
result escapes while a thread still writes it.
for_each_index and map_index split a range into one chunk per thread. Both
take a closure that is only called, never mutated, so the caller shares
input and produces output rather than racing on it. threads_for keeps a
short loop on one thread, because starting a thread to do a few
microseconds of work costs more than the work.
Asking whether an edge already exists scanned the whole edge list, so
building a graph of E edges cost O(E^2). A visibility sweep adds a quadratic
number of edges, so the whole construction was cubic: 600 satellites took
twelve seconds. An index of outgoing edge positions makes the membership
test constant time, and the same index answers neighbours and out-degree
without a scan. Removal rebuilds the index in one pass, since it renumbers
every later position. Six hundred satellites now take 130 ms, a factor of
ninety five.
bench_scale and bench_parallel were runnable but documented nowhere, so the
directory listing did not say they existed. The file header of
bench_scale also still claimed the harness warms up, which it stopped
doing when the cold cost was given its own column.
Splits the three heavy paths across scoped threads and reports the
speedup and the efficiency against the thread count, with the serial time
taken as the fastest of several runs so a scheduling hiccup cannot inflate
the reference every number is divided by.
Constellation propagation and access search are embarrassingly parallel and
scale as expected until the thread count passes eight, where the machine
stops gaining. Topology construction does not scale at all, and the split
line shows why: the geometric visibility test is two milliseconds while
folding the visible pairs into the graph is four hundred, because each
insertion scans the edges already stored.
The warm up hid the first call's allocation and cache cost behind a
discarded run, so the reported figure was one the caller never waits for.
Report the first call separately as the cold cost and the rest as the
steady state, and let the difference speak for itself.
The constellation path now covers a full day at a sixty second step and
sweeps from 24 to 2016 satellites, propagating each satellite at its own
orbital elements so the deep space branch is reached where the period is
long.
bench_scale sweeps the input size over four paths and reports time per
unit, so growth is visible even when absolute times move with the machine.
It shows SGP4 propagation and access search are flat per satellite, while
topology construction is quadratic and planning is quadratic in the number
of tasks.
The README said library code never uses expect, but twelve call sites do,
each guarded by a check on the line above or by construction. Allow that
case explicitly and record each site with its guard in the design notes.
Both crates were verified only against themselves. dump_kepler writes the
element to state conversions and a state back to element round trip, which
check_kepler recomputes from the perifocal formulae, the rotation and the
vis-viva equation. dump_tle writes the parsed fields of eight element sets,
which check_tle reparses with a column indexed reader and a
reimplementation of the modulo ten checksum.
Both network examples repeated the WGS 84 equatorial radius that
apsis-core already exports, so a change to the ellipsoid would not reach
them. Use the constant.
The implemented checks table listed twelve scripts and omitted the coverage
cross-check added alongside it, and the tolerance table listed three
quantities while the scripts use nineteen. Add the row and describe the
tolerances by the physical quantity they apply to.
EphemerisSamplingError and ManeuverApplicationError were missing the
attribute the other fifteen error kinds carry. Record the distinction
between an error enum, which is marked so a new category does not break a
caller, and a domain state enum, which is left exhaustive so the compiler
points at every match that a new variant needs.
The facade crate enables nothing by default, so cargo check and cargo
clippy without --all-features skipped almost all of its code and every
example. A deliberate mistake placed in feature gated facade code was
invisible to the old commands and caught by the new ones.
Running rustdoc with -D warnings found nine broken links: a misspelt
WGS84, links to methods and constants that are private or in a crate that
is not a dependency, and three redundant explicit targets. Fix each and add
a documentation step to CI so a doc comment cannot drift away from the code
it describes without the build noticing.
Thirty four crates listed apsis-core or apsis-math without referencing it,
and apsis-kepler listed apsis-time and apsis-tle as well. Each was verified
removable by compiling with it taken out. An unused dependency still costs
build time and makes the dependency graph and the layer check report
relations that do not exist. The layer check now reports 104 edges, down
from 141.
README stated that a crate may only depend on layers to its left, but
nothing checked it, and the wording was self contradicting: the example
given for a cross layer jump was a reverse dependency. Clarify the rule,
add scripts/check-layers.sh to enforce it, run it in CI, and record the
boundary cases in docs/design/layers.md.
apsis-core described Error and Result as the workspace's single error
surface, but no crate uses them: every layer with a domain specific failure
defines its own Error and ErrorKind, whose variants name the concrete
conditions a caller matches on. Correct the doc comment and record the
strategy, including the Option versus Result split and the tolerance
conventions.
The atmosphere examples directory was empty and untracked, so it never did
anything. The validation .gitkeep files were redundant once their
directories held real content, and data/tle was described as holding TLE
samples that no script reads. Remove all three and correct the README.
The network layer was the only layer without a Python cross-check, and
validation/python/constellation/ was an empty placeholder that the README
described as existing. Add the dump example and the reference script, which
recomputes the geometry from the spherical triangle relations rather than
from the Rust code, and remove the placeholder.
The cross-layer integration checks were examples containing assertions
that cargo test never ran, so a break in one layer's assumptions about
another could pass CI. Run them explicitly.
The benches/ and tests/ directories were empty placeholders that a virtual
workspace does not compile, and benches/criterion named a third party crate
this workspace forbids. Remove both and add a real zero dependency
benchmark as a facade example.
ApsisRS contributors