pitch-angle-distribution

Field-aligned pitch-angle distribution (PAD)

A guided version of the IDL SPEDAS particle pitch-angle crib sheet — take a particle population over an interval and ask the classic question: is it a beam, a pancake, or isotropic, and is there a loss cone? Pitch angle is the angle between the particle velocity and the local magnetic field, so the whole workflow hinges on having a B field to define the field-aligned axis. There is no dedicated "PAD" tool and there should not be: compute_particle_spectra already produces the field-aligned 0–180° spectrum directly. This skill is the procedure and interpretation wrapped around it.

When to use

• "Is this electron/ion population a beam, a pancake, or isotropic?"
• "Show me the pitch-angle distribution / PAD for on ."
• "Is there a loss cone in this interval?" (the field-aligned-vs-perpendicular question PADs exist to answer.)

Tool chain (all already exist)

create_spedas_analysis_bundle → (build_particle_distribution_artifact | load_particle_distribution_artifact, the #95 bridge — give it the B field here via mag_tplot_name=/magf=) → compute_particle_spectra(spectrum_types=["pitch_angle"]) (reuses the artifact's embedded magf) → render_tplot.

Backend (VERIFIED contract)

• Distribution input. compute_particle_spectra(dist_file, output_dir, ...) reads a distribution artifact on disk — not an in-memory array and not a stored tplot variable name. Produce that artifact with build_particle_distribution_artifact (convert a 3D distribution you already have) or load_particle_distribution_artifact (the #95 bridge: fetch/load + convert in one step). Both write the file and return its path; pass that path as dist_file.
• B field comes from the artifact by default (issue #148). The #95 bridge already requires a B field to write the artifact (mag_tplot_name= or magf=) and stores it as embedded magf shaped (T,3). compute_particle_spectra(spectrum_types=["pitch_angle"]) reuses that embedded magf automatically — no separate mag_file needed. The pitch-angle entry reports mag_source: "distribution_artifact_magf". This B defines the field-aligned +z; each slice is rotated into FAC (spd_pgs_do_fac) and the polar/pitch angle is binned over 0–180° (colatitude mode).
• mag_file is an optional override. Pass mag_file only when you want a different B reference than the one embedded in the artifact (e.g. a higher-cadence or differently-framed magnetometer product). It is a separate file (.npz/.json), not a tplot var, holding key b as (T,3) (one B vector per distribution slice) or (3,) (broadcast), in the distribution's own coordinate frame. An explicit mag_file wins over embedded magf; the entry then reports mag_source: "mag_file".
• needs_input, not failure. spectrum_types defaults to ["energy","pitch_angle"]. "pitch_angle" needs a B reference: embedded magf or mag_file. Only when the artifact has no embedded magf and no mag_file is passed does the pitch-angle entry return status: "needs_input" (code needs_input, mag_source: "missing") while any other requested spectra still compute — the call does not hard-fail.
• Output = one matrix per .npz, artifact-first. Each spectrogram is written to output_dir/particle_spectra_<type>.npz as a single (n_time, n_bin) 2-D matrix (here n_bin = pitch-angle bins, axis 0–180°). The tool returns paths + ranges + shapes only, never the arrays. render_tplot then renders exactly one matrix per .npz as a pcolormesh panel.