Optimize Coordinates construction and de-duplicate coordinate syntax docs

docs/source/coordinates.rst

@@ -7,37 +7,13 @@ The tokamak is a curvilinear device which can be described in a number of coordi
 Accepted coordinates types
 --------------------------
 
-**1D - coordinates**
+The accepted coordinate types and the full coordinate input syntax (shared by
+``Coordinates.from_coords``, ``Equilibrium.coordinates`` and all
+coordinate-accepting ``Equilibrium`` methods) are documented in a single
+place:
 
-+------------------------+-----------+------------------------------+
-| Coordinate             | Code      | Note                         |
-+========================+===========+==============================+
-|:math:`\psi_\mathrm{N}` | ``psi_n`` | Default 1D coordinate        |
-+------------------------+-----------+------------------------------+
-|:math:`\psi`            | ``psi``   |                              |
-+------------------------+-----------+------------------------------+
-|:math:`\rho`            | ``rho``   | :math:`\rho = \sqrt{\psi_n}` |
-+------------------------+-----------+------------------------------+
-
-**2D - coordinates**
-
-+------------------------+--------------+-------------------------------------------------+
-| Coordinate             | Code         | Note                                            |
-+========================+==============+=================================================+
-|:math:`(R, Z)`          | ``R, Z``     | Default 2D coordinate                           |
-+------------------------+--------------+-------------------------------------------------+
-|:math:`(r, \theta)`     | ``r, theta`` | Polar coordinates with respect to magnetic axis |
-+------------------------+--------------+-------------------------------------------------+
-
-**3D - coordinates**
-
-+------------------------+---------------+-------------------------------------------------+
-| Coordinate             | Code          | Note                                            |
-+========================+===============+=================================================+
-|:math:`(R, Z, \phi)`    | ``R, Z, phi`` | Default 3D coordinate                           |
-+------------------------+---------------+-------------------------------------------------+
-|:math:`(X, Y, Z)`       | ``X, Y, Z``   |                                                 |
-+------------------------+---------------+-------------------------------------------------+
+.. automethod:: pleque.core.coordinates.Coordinates.from_coords
+   :noindex:
 
 Array shape convention
 ----------------------

examples/example_impact_angle.py

@@ -27,7 +27,7 @@
 
 axn.plot(first_wall.R,first_wall.Z)
 
-coords=Coordinates(eq,np.vstack((first_wall.R,first_wall.Z)).T)
+coords=Coordinates.from_coords(eq,np.vstack((first_wall.R,first_wall.Z)).T)
 
 
 def interpolate_lim(coords, npoints):

examples/example_impact_angle_w_integrated_methods.py

@@ -26,7 +26,7 @@
 
 
 
-coords=Coordinates(eq,np.vstack((first_wall.R,first_wall.Z)).T)
+coords=Coordinates.from_coords(eq,np.vstack((first_wall.R,first_wall.Z)).T)
 
 # Resample using new method
 coords2=coords.resample2(npoints)

pleque/core/cocos.py

@@ -1,3 +1,5 @@
+import functools
+import types
 from typing import TypedDict
 
 import numpy as np
@@ -20,14 +22,18 @@ class CocosInfo(TypedDict):
     sign_q: int
     sign_pprime: int
 
+@functools.lru_cache(maxsize=32)
 def cocos_coefs(cocos_idx) -> CocosInfo:
     """
     Define COCOS coefficients.
 
     For more details see Table 1 in O. Sauter, et al., Comp. Phys. Comm. 184 (2013), p. 296
 
+    The result is cached and shared between callers; it is returned as a
+    read-only mapping.
+
     :param cocos_idx: int, COCOS index
-    :return: dict with COCOS coefficients
+    :return: read-only dict with COCOS coefficients
     """
 
     # Note: sign_q and sign_pprime assumes Ip and B0 to be in direction of a toroidal coordinate.
@@ -65,5 +71,5 @@ def cocos_coefs(cocos_idx) -> CocosInfo:
         cocos["sigma_pol"] = -1
         cocos["sign_q"] = -1
 
-    return cocos
+    return types.MappingProxyType(cocos)