These instructions apply to the entire GWCS.jl repository.
GWCS.jl is a compiled, composable numeric WCS implementation. Optimize for:
- Correct forward and inverse coordinate results.
- Inferred, allocation-free scalar evaluation.
- Static dimensions and concrete execution types.
- Easy programmatic construction and extension.
- Faithful parsing of Python GWCS and ASDF metadata.
Pipeline construction may perform extra validation, normalization, fusion, precomputation, and compilation when that makes repeated evaluation faster. Keep metadata lookup, schema interpretation, frame bookkeeping, units, and dynamic graph traversal out of the scalar execution path.
- Treat
pixel_to_worldandworld_to_pixelscalar calls as hot paths. - Preserve type inference and zero allocations for representative analytical scalar transforms after warm-up.
- Use
StaticVectorandStaticMatrixvalues in scalar kernels. - Encode input and output dimensions in types through
AbstractTransform{Nin,Nout}. - Store concrete transforms in tuples or other specialization-friendly structures. Avoid abstractly typed transform collections in evaluation code.
- Compile or canonicalize transforms during
WCSconstruction rather than interpreting a mutable graph during evaluation. - Precompute matrices, permutations, inverse data, dependency information, and other reusable values.
- Benchmark dispatch or abstraction layers against direct transform evaluation when adding them.
- Do not trade clear correctness for speculative micro-optimizations. Add generated functions or complex specialization only when inference or measurements justify them.
- Keep high-level coordinate construction, units, and metadata objects outside the compiled numeric kernel.
- Construction and first-call compile latency matter as well as per-call speed. Avoid designs that multiply pipeline types per WCS, such as storing several specialized copies of the same pipeline.
- New numeric transforms should subtype
AbstractTransform{Nin,Nout}. - Implement scalar evaluation as
transform(coords::StaticVector{Nin}) -> StaticVector{Nout}. - Extend the established protocol as appropriate:
inverse_transformcompile_transformtransform_jacobiantransform_dependenciestransform_nameinput_namesoutput_names
- Return
NoInverse()when no analytical or explicit inverse exists. Do not invent an inverse merely because each component appears invertible. - Return
NaNin every output component where a coordinate has no image (an undefined analytical inverse, a point off a projection, an output outside a constrained slice); do not throwDomainErrorfrom transform evaluation. The evaluation API turns finite input that yieldsNaNintofill_value, or into a diagnosedDomainErrorwithstrict=true. Zero-dimensional results, which cannot carryNaN, are the only exception. - Outer constructors should compute type parameters and delegate inward so all call forms apply the same conversions.
- Parametric inner constructors must accept unconstrained values and let field declarations or
newperform conversion. Do not require arguments to already have the field type. - Propose any API-breaking change and get the maintainer's approval before making it; never break an API on your own initiative. While GWCS.jl is below 1.0, a breaking change needs a minor version bump. The README documents what the package currently does, not its history, so describe the new behavior there rather than the change.
Composition with | is left to right. Parallel composition with & operates on consecutive input slices. Elementwise arithmetic sends the same inputs to both operands. Preserve these semantics when simplifying or compiling transform trees.
Labels are dispatch metadata, not numeric coordinates. Keep AbstractLabelMapper separate from AbstractTransform.
- A label mapper returns a concrete label or
nothing. nothingmeans no match; do not reserve0or""as universal Julia sentinels.RegionSelectorevaluates toNaNwhen no branch applies. Itsundefined_value(Python GWCS'sundefined_transform_value) is stored only so ASDF files round-trip exactly, and the inverse selector does not inherit it, as in Python GWCS.- Keep region selection separate from input domains. A
CompoundBoundingBoxdecides domain membership; a label mapper decides which transform applies. - Match Python GWCS semantics deliberately when parsing its metadata. For example, dictionary label matching uses NumPy's asymmetric
iscloserule, not Julia'sisapproxrule. - Construct an inverse region selector only when the inverse label mapper and every branch provide compatible inverses.
Transform order is the order of a transform's inputs and outputs, and it is the order of every public coordinate. Frame order is the order in which a frame stores its own axes: a CelestialFrame is (lon, lat), and a CompositeFrame concatenates its constituents. axes_order[i] is the one-based transform position of the frame's axis i, so it labels coordinates and never reorders them; a constituent's entries are positions in the whole composite. This is Python GWCS's convention.
- Public coordinates, the axis accessors (
axis_names,world_axis_physical_types, and so on), bounding boxes,pixel_shape, andfix_inputsindices use transform order. Frame fields and constructor arguments use frame order. - ASDF per-axis frame lists are in frame order, which is how Python GWCS reads them and, since gwcs#687, writes them.
- Do not add an implicit zero- or one-based pixel offset. Encode external pixel-origin conventions explicitly at interoperability boundaries.
- Matrix evaluation uses one coordinate per column.
in_domaintests finite input coordinates against the input domain.in_imagerequires successful finite inversion and optionally enforces the input domain.- Ignored bounding-box axes are geometrically unconstrained but must still be finite for validity predicates.
- Unknown compound selectors are outside the domain.
- Keep input-domain masks distinct from future output-footprint geometry.
- Metadata parsing is a construction-time concern. Parsed WCS objects must contain concrete compiled transforms.
- Produce path-aware errors for malformed metadata.
- Validate schema versions explicitly; do not assume all future
1.xtags are compatible. - Use
register_transform!for externalAbstractTransformmetadata support. - Do not force label mappers into the transform-registration API.
- Preserve ASDF.jl as a weak dependency and adapt its tagged or lazy values through the package extension.
- GWCS.jl owns FITS WCS keyword interpretation (
src/fits.jl); delegate FITS container I/O to FITSIO.jl or FITSFiles.jl and ASDF container I/O to ASDF.jl. Do not reimplement those container formats here. - When behavior is intended to match Python GWCS, Astropy, NumPy, or WCSLIB, verify the exact convention rather than substituting a similar Julia API.
- For FITS WCS semantics, WCSLIB is the source of truth, settled from its source or a direct WCSLIB run. Always cross-check astropy as well, since it normalizes headers and implements SIP and Paper IV distortions itself; when the two disagree, state which one GWCS.jl matches and why.
- A serialization round trip must reproduce the WCS mathematically, not the source tree. Preserve frames, annotations (names, inputs, outputs), explicit inverses, and bounding boxes, and change values at most by rounding.
composeandparallelmay canonicalize unannotated transforms, so every form a stored step can take needs a serializer that writes standard tags Python GWCS reads. - Keep rich units and high-level coordinate objects in optional extensions unless the numeric core requires them.
- Fail explicitly on invalid dimensions, ambiguous metadata, incompatible inverses, and unsupported operations.
- Do not use broad catches, silent defaults, or success-shaped fallbacks. Returning
fill_valuefor coordinates without a result is the deliberate APE 14-style default, not a fallback; fail explicitly on invalid inputs, parameters, and metadata. - Catch only errors that have defined public meaning. For example,
in_imageconverts theDomainErrorof a zero-dimensional inverse tofalse(it reads numerical non-convergence from the solver's status rather than catchingNoConvergence), andCallableTransformconverts aDomainErrorfrom user code toNaN. - Preserve useful diagnostic information in errors such as
NoConvergence.
- Use American spelling.
- Keep function calls and signatures on one line when they reasonably fit.
- Avoid gratuitous vertical argument lists, line breaks, blank lines, and trailing commas.
- Prefer compact, idiomatic Julia over deeply layered helper abstractions.
- Use short keyword syntax when the variable name matches:
f(; maxiter), notf(; maxiter=maxiter). - Comment only non-obvious logic. Explain why a step exists rather than restating the code.
- Follow nearby naming, docstring, export, and file-layout conventions.
- Do not run formatters or broad whitespace normalization unless explicitly requested.
- Keep diffs focused on the requested behavior.
- Julia 1.10 is the minimum supported release. New syntax and dependencies must work there.
- Do not add dependencies unless they clearly reduce maintenance burden or are explicitly required.
- When adding a package, add a bounded
[compat]entry compatible with Julia 1.10 and runPkg.resolve(). - Prefer optional extensions for units, coordinate objects, file containers, and specialized observatory functionality.
- Read the relevant implementation and existing tests before editing.
- Run the narrowest relevant test file or testset first.
- Add regression tests for concrete failure modes, boundary conventions, dimensions, inverses, dependencies, inference, and allocations.
- Warm up code before checking
@allocated. - Use a typed helper around
@allocatedwhen testing Julia 1.10; global or freshly defined testset wrappers can introduce measurement artifacts. - Cross-check analytical inverses with forward round trips.
- Test zero-dimensional and matrix forms when the API supports them.
- For metadata features, test programmatic construction and tagged parsing separately.
- Add Python-produced or Python-validated fixtures for Python GWCS compatibility features.
- Run
Pkg.test()only when the change is coherent and targeted tests pass. - Before completion, run the full suite on current stable Julia and Julia 1.10.
- Run
git diff --check. - Use a long timeout when running full package tests (e.g., 10 min).
Prefer a persistent Julia session with Revise.jl over launching a fresh Julia process for each edit-test loop.
Python reference work uses the uv environment described in validation/README.md; set GWCS_PYTHON to use another interpreter.
- Add benchmark coverage for new transform families or dispatch mechanisms.
- Compare equivalent FITSWCS.jl and GWCS.jl paths where possible.
- Report allocations as well as time.
- Keep benchmark construction separate from evaluation benchmarks.
- Extend validation scripts when implementing externally defined semantics.
- Document deliberate differences from Python GWCS rather than allowing accidental divergence.
Every exported and public name has a docstring, which the test suite checks. The documentation build's checkdocs = :public checks that each one appears in the manual.
- Start with every call form as an indented signature, giving keyword defaults and, where it helps, the return type:
pixel_to_world(wcs, pixels...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0) -> SVector. Matrix and grid forms get their own lines. - Follow with one sentence on what the function returns or does, then the details users get wrong: coordinate order (transform order or frame order), units, the pixel origin, what is returned for a coordinate without a result (
NaN,fill_value,NoInverse,nothing), and the errors thrown for invalid input. - Describe keywords in prose, in signature order. Document a keyword set that several functions share once, on the main function (
pixel_to_world), and refer to it from the others. - Write one docstring per function, on its main method, covering every method. Document a type's constructors in the type's docstring. Give an enum a docstring that lists its values, and each value a one-line docstring, since the documentation check counts each binding.
- Link related names with
[`name`](@ref)where the text mentions them. - Use a
jldoctestblock for an example only when its output is short and exact, such as frame names, tuples, integers, or values with few digits, and a plainjuliablock otherwise. An example builds what it needs, so it runs on its own. Doctests run with the test suite, not in the documentation build. - End with
Python equivalent: `<full public path>`.when Python GWCS or astropy has one, naming any behavior difference in the same sentence, and omit the line when there is none. Check the equivalent against the Python source. Describe the Julia behavior in its own terms above it, and mention Python in the body only where it defines the behavior. - Wrap prose at 120 columns, as in the code.
- Update the README for new public APIs, conventions, restrictions, and compatibility differences.
- Update
feature_list.mdwhen completing or splitting checklist items. - Keep deferred work explicit, especially when correctness depends on future geometry, units, batching, or serialization design.