Skip to content

Comments

New Grid API#2053

Open
ddudt wants to merge 86 commits intomasterfrom
dd/grids
Open

New Grid API#2053
ddudt wants to merge 86 commits intomasterfrom
dd/grids

Conversation

@ddudt
Copy link
Collaborator

@ddudt ddudt commented Jan 7, 2026

Resolves #1840

Restructures and generalizes the Grid classes. The new ABC AbstractGrid that all other grids inherit from does not assume a particular coordinate system. The new ABC AbstractGridFlux is specific to ($\rho,\theta,\zeta$) coordinates and is the parent class of all existing grid classes in flux coordinates. Most of the changes involved moving existing code into one of these new ABCs.

The goal is to allow for new grid classes in the future that represent other coordinate systems, without changing the existing public API.

To-Do:

  • Ensure tests pass
  • Generalize Basis dimensions (no references to flux coords)
  • Include isinstance(grid, AbstractGridCurve) checks wherever appropriate
  • Add 1D grids for Curve objects
  • Add 2D grids for FourierRZToroidalSurface objects
  • Alias flux grid class names like Grid -> CustomGridFlux, etc. (do not deprecate)

@ddudt ddudt self-assigned this Jan 7, 2026
@ddudt ddudt added interface New feature or request to make the code more usable or compatibility with another code functionality New feature or request to do things the code can't do now. enhancement General label for enhancement. Please also tag with "Speed", "Interface", "Functionality", etc labels Jan 7, 2026
and self.grid.NFP != self.basis.NFP
and self.basis.N != 0
and grid.node_pattern != "custom"
and not isinstance(grid, Grid)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is equivalent to the old code, since the old Grid class was hard-coded to have node_pattern="custom". In the new code, node_pattern is only an attribute of the ConcentricGrid class.

@dpanici
Copy link
Collaborator

dpanici commented Jan 7, 2026

Add checks in objectives and inside geometric/magneticfield/coil compute methods to ensure grids passed in are correct (i.e. 1D for a filament coil, 3D for finite build coil, 1D or 2D rtz for surface)

@dpanici
Copy link
Collaborator

dpanici commented Jan 7, 2026

Rename AbstractRTZGrid to AbstractGridFlux instead of RTZ

@github-actions
Copy link
Contributor

github-actions bot commented Jan 7, 2026

Memory benchmark result

|               Test Name                |      %Δ      |    Master (MB)     |      PR (MB)       |    Δ (MB)    |    Time PR (s)     |  Time Master (s)   |
| -------------------------------------- | ------------ | ------------------ | ------------------ | ------------ | ------------------ | ------------------ |
  test_objective_jac_w7x                 |    1.92 %    |     3.843e+03      |     3.917e+03      |    73.83     |       38.77        |       35.84        |
  test_proximal_jac_w7x_with_eq_update   |   -0.75 %    |     6.614e+03      |     6.564e+03      |    -49.76    |       160.17       |       158.04       |
  test_proximal_freeb_jac                |    0.12 %    |     1.322e+04      |     1.323e+04      |    16.08     |       83.02        |       80.99        |
  test_proximal_freeb_jac_blocked        |   -0.32 %    |     7.564e+03      |     7.540e+03      |    -24.30    |       72.80        |       71.30        |
  test_proximal_freeb_jac_batched        |    0.20 %    |     7.479e+03      |     7.494e+03      |    15.05     |       72.90        |       73.29        |
  test_proximal_jac_ripple               |   -2.18 %    |     3.631e+03      |     3.552e+03      |    -79.10    |       63.47        |       64.59        |
  test_proximal_jac_ripple_bounce1d      |   -1.00 %    |     3.548e+03      |     3.512e+03      |    -35.59    |       74.33        |       74.43        |
  test_eq_solve                          |   -1.13 %    |     2.034e+03      |     2.011e+03      |    -23.03    |       92.25        |       91.33        |

For the memory plots, go to the summary of Memory Benchmarks workflow and download the artifact.

@codecov
Copy link

codecov bot commented Jan 7, 2026

Codecov Report

❌ Patch coverage is 87.62963% with 167 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.25%. Comparing base (29c7877) to head (1510a29).

Files with missing lines Patch % Lines
desc/grid/surface.py 80.80% 43 Missing ⚠️
desc/grid/flux.py 77.90% 38 Missing ⚠️
desc/grid/curve.py 75.35% 35 Missing ⚠️
desc/grid/core.py 94.17% 11 Missing ⚠️
desc/geometry/core.py 71.42% 8 Missing ⚠️
desc/objectives/_geometry.py 83.33% 7 Missing ⚠️
desc/external/terpsichore.py 0.00% 6 Missing ⚠️
desc/plotting.py 93.93% 6 Missing ⚠️
desc/coils.py 88.88% 2 Missing ⚠️
desc/grid/utils.py 98.56% 2 Missing ⚠️
... and 7 more
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2053      +/-   ##
==========================================
- Coverage   94.52%   94.25%   -0.28%     
==========================================
  Files         102      107       +5     
  Lines       28785    29346     +561     
==========================================
+ Hits        27210    27659     +449     
- Misses       1575     1687     +112     
Files with missing lines Coverage Δ
desc/basis.py 97.74% <100.00%> (ø)
desc/compat.py 88.61% <100.00%> (ø)
desc/compute/_geometry.py 97.70% <100.00%> (-0.77%) ⬇️
desc/compute/_neoclassical.py 100.00% <ø> (ø)
desc/compute/_old.py 100.00% <ø> (ø)
desc/compute/data_index.py 95.89% <ø> (ø)
desc/compute/utils.py 97.71% <100.00%> (+0.01%) ⬆️
desc/equilibrium/initial_guess.py 93.79% <100.00%> (ø)
desc/geometry/curve.py 96.44% <100.00%> (ø)
desc/geometry/surface.py 97.61% <100.00%> (+0.01%) ⬆️
... and 38 more

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Comment on lines 1948 to 1958
r_grid = Grid(
map_coordinates(
eq,
r_grid.nodes,
["rho", "theta", "phi"],
["rho", "theta", "zeta"],
period=(np.inf, 2 * np.pi, 2 * np.pi),
guess=r_grid.nodes,
),
sort=False,
)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this code necessary or was it only anticipating the future change where $\zeta \neq \phi$?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't remember what was the reason to revert this but at some point in #1683 (comment) I removed this line, and in the dev meeting we changed our minds, can't remember why though

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surely there was a reason though. I'd rather not change this now if we don't have a good reason for changing it at the moment

Comment on lines 4 to 7
Breaking Changes

- Restructures the grid classes to allow for new grids in different coordinate systems besides flux coordinates. The old grid classes are aliased to the new grids of type ``AbstractGridFlux`` and are backwards compatable with the new API. ``Curve`` objects now require a compute grid of type ``AbstractGridCurve``, and ``FourierRZToroidalSurface`` objects now require a compute grid of type ``AbstractGridSurface``.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should release a new version of DESC after this is merged, since it does change the API for things like coil optimizations and REGCOIL runs.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add deprecation warnings for curve and surface as well

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement General label for enhancement. Please also tag with "Speed", "Interface", "Functionality", etc functionality New feature or request to do things the code can't do now. interface New feature or request to make the code more usable or compatibility with another code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New Grid API

6 participants