Chartmap: keep periodic grids endpoint-excluded in files and append endpoints only internally

[krystophny]

Problem

The chartmap file format should not store redundant endpoint planes for periodic quantities. Periodicity is part of the coordinate convention; the file should contain only unique angular samples.

The durable file-level convention should be:

• theta[j] = j * 2*pi / ntheta, j = 0..ntheta-1, endpoint excluded.
• zeta[k] = k * (2*pi/num_field_periods) / nzeta, k = 0..nzeta-1, endpoint excluded.
• All periodic variables use those endpoint-excluded dimensions in the file.
• Any endpoint-included arrays needed by the spline backend are constructed internally by the reader / spline setup code, not written to NetCDF.

The current chartmap validator already enforces endpoint-excluded periodic grids for theta and zeta, but downstream users can still leak spline-constructor details into their file schema by storing separate endpoint-included periodic variables.

Required changes

1. Make the chartmap convention explicit in libneo docs and/or validator comments:

   • angular coordinates in the file are endpoint-excluded;
   • redundant endpoint planes are not part of the chartmap format;
   • periodic closure is a reader/spline-construction responsibility.

2. Add reusable internal helpers for periodic extension before calling the current spline backend, e.g.

   • scalar periodic extension in theta and/or zeta by copying the first plane;
   • vector/geometry extension only after the representation is actually periodic. For Boozer Cartesian geometry this must wait for / use a rotating-frame representation, not raw x,y,z.

3. Keep the spline backend free to use endpoint-included temporary arrays if needed, but do not require endpoint-included variables in NetCDF.

4. Decide and document the compatibility policy for legacy files that contain redundant endpoint-included variables outside the base chartmap schema.

Acceptance criteria

• The documented chartmap convention is unambiguous: endpoint-excluded periodic grids in files; internal endpoint construction only.
• No new chartmap writer in libneo writes redundant angular endpoint planes.
• Readers construct exact closure internally where required by construct_batch_splines_3d.
• Existing base chartmap validation remains strict about endpoint exclusion.

Fast and reliable tests required

Add tests at multiple levels, with small grids so they are fast in CI:

1. Unit tests for periodic extension helpers:

   • scalar values append exactly first theta/zeta slice;
   • no interpolation or floating-point re-evaluation is used to create the duplicate endpoint;
   • shape, x_min, x_max, and implied h_step are correct.

2. Validator tests:

   • endpoint-excluded theta/zeta accepted;
   • endpoint-included angular coordinate arrays rejected for base chartmap coordinates.

3. Spline smoke tests:

   • an endpoint-excluded periodic analytic scalar is extended internally and evaluates continuously across the seam;
   • tests must cover both theta and zeta periodicity.

4. Regression tests for representative chartmap files generated by libneo tools, ensuring they contain no redundant angular endpoint planes.