Environmental inputs and attitude#
The orbitalpv.environment_data API connects environmental measurements to
explicit physical models. Every file download returns a checksum receipt;
local readers preserve source units and metadata. Live catalog checks and one
public NOAA day underpin analysis/environmental_inputs. The gallery runs
offline using a checked, reduced observation snapshot.
Install orbital-pv[netcdf] for netCDF readers and orbital-pv[orbit] for
SPICE. These dependencies are imported only when their functions are called.
CERES: choose a collection and edition#
NASA’s current CMR cloud catalog separates short name from version. Discover the exact current identifiers before requesting a bounded interval:
from orbitalpv import environment_data as env
with env.CeresConnector() as ceres:
collections = ceres.collections(short_name_pattern="CER_SYN1deg*")
granules = ceres.search(
short_name="CER_SYN1deg-1Hour_Terra-Aqua-NOAA20",
version="Edition4B",
start="2023-01-01T00:00:00Z",
end="2023-01-01T23:59:59Z",
)
The checked catalog result contains one daily file with hourly fields for this
interval. Discovery is public; file retrieval may require an Earthdata token.
Pass an authorized token through download(..., bearer_token=token). It is
not written to receipts. Query strings are redacted, but a digest of the full
request URL preserves cache identity so different subsets cannot be confused.
An existing file with incompatible provenance raises instead of being reused.
Use inspect_environment_netcdf to identify an exported file’s exact
variables. read_ceres_toa requires explicit shortwave and longwave names,
checks W/m² units and decoded time, and applies optional isel selectors
before loading. It reads CF-netCDF; HDF4 is not silently interpreted as netCDF.
Missing or invalid flux remains missing. Edition-specific quality flags should
be screened before using values as model forcing.
Top-of-atmosphere hemispheric flux is not panel irradiance. The
earth_flux_to_panel integration applies the emission angle, receiver angle,
patch area and inverse distance squared, assuming Lambertian radiance
\(L=F/\pi\). Spacecraft position, panel normal and geographic patches must
share the same Earth-fixed frame. earth_grid_cell_areas computes exact
spherical cell areas from edges.
Missing visible supplied cells produce NaN by default. allow_partial=True
returns only the measured portion and its view-weight coverage; it does not
extrapolate missing Earth radiation. valid_view_fraction measures finite
values among supplied patches, not completeness of the whole Earth disk.
geometric_view_factor exposes the projected quadrature weight; values above
1.01 are rejected as physically impossible, requiring finer or nonoverlapping
patches. Anisotropic reflection, atmospheric limb effects and grid resolution
remain model discrepancy. Thermal IR is thermal forcing and
must not be passed to a solar photon-conversion model as ordinary sunlight.
POES/MetOp: retain instrument definitions#
with env.PoesMetopConnector() as noaa:
receipt = noaa.fetch_day("metop01", "2023-01-01", "data/metop.nc")
variables = env.inspect_environment_netcdf(receipt.path)
particles = env.read_poes_metop(
receipt.path,
channels=["mep_pro_tel0_flux_p1", "mep_ele_tel0_flux_e1"],
quality_variables=["mep_pro_tel0_flux_p1_err"],
)
The real source contains 43,199 approximately two-second observations. Its
native time metadata specifies milliseconds since 1970 in long_name while
units is simply time. The reader recognizes this exact NOAA format,
including its independent, same-length record dimensions, and also accepts
ordinary CF epoch time. It rejects ambiguous numeric time from other files.
The proton channel is differential near 39 keV; the electron channel is integral
above 40 keV. They have different units and cannot be added. Provider metadata
reports known contamination and a calibrated-flux processing level even though
the archive path contains l1b; both remain visible. The loader preserves
negative provider sentinel values. Explicit filtering, valid-count reporting
and instrument-specific contamination correction belong to the analysis.
These are measurements at the detector’s location and orientation. Using them
for another mission requires environment mapping and energy/angular response;
solar-cell degradation additionally needs exposure duration, shielding and
calibrated damage response. physics.radiation_equivalent_fluence requires
those physical inputs and never takes a raw integral channel as NIEL dose.
SPENVIS and IRENE exports#
read_spenvis(path) and parse_spenvis(text) implement the documented
SPENVIS/UNIRAD block-CSV format: comments, metadata, reserved annotations,
scalar/vector variable descriptions, numeric records and block footers.
FORTRAN D exponents and escaped apostrophes are supported. Header/column/row
inconsistency, truncation and provider error markers raise exceptions.
Returned SpenvisBlock objects retain exact units, metadata and vector-energy
associations; no keV/MeV, integral/differential, confidence percentile, shielding
or model-version assumptions are inferred. Select and convert those explicitly
before a radiation model. The importer can read SPENVIS-formatted IRENE output;
arbitrary IRENE text/JSON formats are not claimed to be supported. It does not
log in to or run a remote SPENVIS service.
Historical orbit and SPICE attitude#
SpaceTrackConnector.gp_history retrieves a bounded UTC EPOCH interval for
one NORAD identifier and sorts returned records by epoch. It checks satellite
identity and date bounds and rejects truncated results. A caller-provided disk
cache is mandatory, respecting Space-Track’s instruction to download history
once and reuse it. Authentication is needed on cache misses; year/bulk archives
are appropriate for larger requests. EPOCH is the element epoch, not the date
the provider published the elements, so causal retrospective studies need to
account separately for availability time.
load_kernels, utc_to_ephemeris_seconds, frame_rotation_matrices and
transform_vectors expose SPICE time/frame operations. Rotations map column
vectors from from_frame to to_frame. CK attitude needs suitable CK, FK,
SCLK and time kernels covering every epoch. Missing coverage or unknown frames
raise the SPICE error; no synthetic attitude fills the gap. Call
clear_kernels after an isolated calculation. The global SPICE kernel pool
must be coordinated by callers sharing a process.
Evidence and reproduction#
The default Earth-view reference is a declared uniform 240 W/m² Lambertian
Earth. Its independent nadir result is \(F(R/r)^2\). The netCDF and
SPENVIS tests use explicitly constructed fixtures, while the NOAA gallery
uses an actual public observation snapshot. Protected CERES observations are
not bundled. See analysis/environmental_inputs/README.md for exact
commands, checksums and the executed reference results.