Add 1D grid file support for fieldline_geometry component

[PoloidalLloyd]

Purpose

Rather than relying on analytical expressions to define geometry such as fieldline radius or poloidal magnetic field, these could be provided exactly from full 2D equilibria and included via a 1D grid file, similar to how goemetry is specified in 2D. This PR adds options to read geometry features from a 1D grid file if present.

Change Summary

Minor alterations to fieldline_geometry.cxx component, with additions allowing for grid specification of lambda_int, fieldline radius, and poloidal/toroidal field.

Validation

Post-processed whether output fieldline_geometry components match input grid file profiles. See example below.

AI Assistance

Yes, minor AI usage to help merge personal fork with newer fieldline_geometry commit on master. Implementation of the grid file methods was done myself, copying other grid file collection methods from the rest of the code base.

Documentation

TODO: Add documentation on ability to specify geometry with 1D grid file.

Review Notes

In regards to tests, should we include a separate test to verify if component is correctly matching 1D grid inputs?

[codecov]

Codecov Report

❌ Patch coverage is 68.62745% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.43%. Comparing base (293d166) to head (bdf4d27).

Files with missing lines	Patch %	Lines
src/fieldline_geometry.cxx	68.62%	12 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #622      +/-   ##
==========================================
- Coverage   57.51%   57.43%   -0.09%     
==========================================
  Files          98       98              
  Lines       10239    10257      +18     
  Branches     1469     1473       +4     
==========================================
+ Hits         5889     5891       +2     
- Misses       3758     3770      +12     
- Partials      592      596       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mikekryjak]

Thanks @PoloidalLloyd! I found one possible problem with guard cell handling.

I think a good unit test would put all these fields in a fake grid file and make sure they exist. Just one test is fine. Here is an example of a unit test that makes a fake mesh and inserts quantities into it:

hermes-3/tests/unit/test_neutral_full_velocity.cxx

Lines 27 to 31 in a1c3ba3

	static_cast<FakeMesh*>(bout::globals::mesh)
	->setGridDataSource(new FakeGridDataSource{{// Missing Rxy
	{"Zxy", 0.0},
	{"hthe", 1.0},
	{"Bpxy", 1.0}}});

[mikekryjak]

mesh->get() only reads domain cells. I'm guessing the guard cells aren't touched and will be zero. Does that cause any problems? I notice that fieldline_geometry loops over the whole grid including guards:

hermes-3/src/fieldline_geometry.cxx

Lines 135 to 138 in bdf4d27

	BOUT_FOR(i, lpar.getRegion("RGN_ALL")) {
	lambda_int[i] = lambda_int_function->generate(
	bout::generator::Context().set("lpar", lpar[i] * Lnorm))
	/ Lnorm;

I can't think of a reason why we'd need these quantities on the boundary. But there are some operations in fieldline_geometry that divide by them, so there could be an issue if some cells are 0:

hermes-3/src/fieldline_geometry.cxx

Line 263 in bdf4d27

coord->J(0, j) = 1 / effective_magnetic_field_strength(0, j, 0) / Lnorm;