Stability
virgil has two tiers.
- Stable: a change needs a deprecation cycle. A release keeps accepting the old form and warns before the new one replaces it.
- Provisional: new features still settling. The name, signature, defaults and output may change in any 0.4.x release without a deprecation.
Everything public not listed below is stable. Provisional pages and API entries carry this notice:
Provisional
May change in any 0.4.x release without a deprecation cycle.
Nothing warns at runtime. The tier lives in the documentation and in each module's __provisional__ tuple, which a test checks. New public features start provisional and are promoted at a release.
Provisional in 0.4
| Area | Provisional names |
|---|---|
| Orbit fitting | the modules virgil.epochs, virgil.aliases, virgil.arcs, virgil.orbit_search and virgil.tempering (the whole of each) |
MultipoleDisk family (virgil.models) |
MultipoleDisk, ThinRing, GaussianRing, RadialPowerLaw, ExpTail, Gap, RadialSum, RadialLinear, RadialPower, RadialGP, RadialGPFunction, MultipoleKernel, Harmonics, VonMises, Cone, PowerLawHeight, multipole_disk_cvis, gp_priors |
Polar fields (virgil.fields) |
MultipoleField, multipole_field_priors |
Ensembles' Gaussian-process members (virgil.ensemble) |
evidence_grid, gp_members, GPFit, EvidenceGrid |
| Variational inference | the module virgil.svi (variational, VariationalResult) |
| Pipelines | the whole of virgil.pipeline: BinaryPipeline, StarPipeline, OrbitPipeline, Result, load and the rest. Promoted to stable after a release of use |
Sparse imaging (virgil.imaging) |
clean, CleanResult |
| Fourier-transform choice | the ft argument of Image, FlaredDisk* and image_visibilities, set_ft_defaults, its automatic thresholds and its tolerances |
| Rendered disks on uv lattices | the rotation_deg argument of FlaredDisk* and its "grid" default; the lattice tolerance for DISCO dictionaries |
Diagnostic plots (virgil.plotting) |
plot_field_draws |
Preconditioned fits (virgil.fitting) |
gauss_newton_diag and the precondition argument of fit |
| Radio interferometry | the module virgil.radio (ComplexVisData, CalibrationNuisance, primary_beam, dartboard_folds; site names, default priors and the measurement-set convention) |
| Radio Toeplitz χ² | the module virgil.radio_toeplitz (ToeplitzVisData), ComplexVisData.toeplitz, and the scalar-term protocol of fit (chi2_and_log_norm, curvature_params, curvature_loss) |
| Radio CLEAN | the module virgil.radio_clean (clean, RadioCleanResult, fit_beam, restore) and the uvtaper argument of ComplexVisData.dirty_image and dirty_beam |
| Image smoothing | Image(smooth_fwhm_mas=...), Image.smoothed() and the smoothed option of the regularizers |
| Image-recovery scores | the module virgil.metrics |
| Cross-validation | the module virgil.crossval (cv_task, cross_validate, aggregate, aggregate_files, fold_masks, save_record, load_records) |
The user-guide pages about these features carry the same notice: orbits, MultipoleDisk rings, CLEAN, ensembles, variational inference and pipelines, radio interferometry (with its Toeplitz χ²), radio CLEAN and cross-validation.
The authoritative list is each module's __provisional__ tuple (("*",) means the whole module), checked by tests/test_stability.py.