Coverage for webgeodyn/data/__init__.py: 0%

1""" 

2 

3The module implements `GHData`_ or `TSData`_ classes that are used to store measure data. 

4 

5 - `GHData`_ contains data described by :math:`g_l^m` and :math:`h_l^m` spherical harmonics coefficients. This includes magnetic field ('MF') or secular variation ('SV'). 

6 - `TSData`_ contains data described by a poloidal/toroidal decomposition of spherical harmonics coefficients (:math:`tc_l^m`, :math:`ts_l^m`, :math:`sc_l^m`, :math:`ss_l^m`). This includes the core flow ('U') or its horizontal divergence ('DIVHU'). 

7 

8`MeasureData`_ is the parent class containing common features of `GHData`_ and `TSData`_ 

9 

10Data creation 

11############# 

12 

13Creation of a new measure is done by instancing `GHData`_ or `TSData`_: 

14 

15.. code-block:: python 

16 

17 from webgeodyn.data import GHData, TSData 

18 from webgeodyn.data.normPnm import semiNormalisedSchmidt 

19 

20 PnmNorm = semiNormalisedSchmidt 

21 myData = GHData(data, lmax, units, measureType, PnmNorm, gridth=tharray, gridph=pharray): 

22 # data : 

23 # 2D array [times, harmonics coefficients] 

24 # or 3D array [times, harmonics coefficients, realisations] 

25 # lmax : int 

26 # units : string 

27 # measureType : "MF", "SV" or "U" 

28 # PnmNorm : normalisation function 

29 # gridth (optional) : array containing list of theta points 

30 # gridph (optional) : array containing list of phi points 

31 

32 

33`normPnm`_ contains normalisation functions for Legendre functions : 

34 

35 - `semiNormalisedSchmidt`_ returns Schmidt semi-normalised coefficients (default). 

36 - `noNorm`_ should be used instead when no normalisation is desired. 

37 

38Operation on data 

39################# 

40 

41Setting data 

42------------ 

43 

44To set a new data array for `GHData`_ or `TSData`_, use the ``setData`` function (overwriting directly data arrays may cause errors when computing data): 

45 

46.. code-block:: python 

47 

48 myData.setData(newdata) 

49 # newdata : 

50 # 2D array [times, harmonics coefficients] 

51 # or 3D array [times, harmonics coefficients, realisations] 

52 

53Evaluating values into real space 

54--------------------------------- 

55 

56To compute values on the globe (on given :math:`r`, :math:`\\theta`, :math:`\phi`), use the ``computeRThetaPhiData`` function: 

57 

58.. code-block :: python 

59 

60 globeData = myData.computeRThetaPhiData(r, thlist, phlist, components=["th","ph","norm"], usegridPnm=False, computeallrealisation=False, irealisation=-1) 

61 

62 # Returns a dictionary containing for each component (r, theta, phi, norm), a 3D array [times, theta, phi] 

63 # (if computeallrealisation=True, the returned array is 4D [times, theta, phi, realisations]) 

64 # 

65 # r : (float) radius 

66 # thlist : (array or list) list of theta points where the values are to be calculated 

67 # phlist : (array or list) list of phi points where the values are to be calculated 

68 # phlist or thetalist must contain unique values [theta] or [phi] 

69 # components : list of components to be calculated. Can contain "r", "th", "ph", "norm" for GHData and "th", "ph", "norm", "divh" for TSData. 

70 # usegridPnm : Whether to use precalculated Pnm for listed th and ph values (warning, use only if thlist and phlist are equal to myData.th and myData.ph) 

71 # computeallrealisation: (boolean) 

72 # if True, returns a 4D array [times, theta, phi, realisations] 

73 # if False, returns a 3D array [times, theta, phi] 

74 # irealisation: (int) 

75 # if irealisation<0, returns a 3D array [times, theta, phi] corresponding to the mean of realisations 

76 # if irealisation>0, returns a 3D array [times, theta, phi] corresponding to the ith realisation 

77 

78 

79Conversion from array index (:math:`k`) to degree, order (:math:`l`, :math:`m`) 

80------------------------------------------------------------------------------- 

81 

82To convert :math:`g_l^m` to/from :math:`k`, the index in the data array, use ``lm2k`` or ``k2lm``: 

83 

84.. code-block :: python 

85 

86 k = myData.lm2k(l, m, coef) 

87 # l (equivalent to n in other notations) : integer 

88 # m : integer 

89 # coef : 

90 # "g" or "h" for GHData 

91 # "tc", "ts", "sc", or "ss" for TSData 

92 # 

93 # returns : 

94 # k : integer index 

95 

96 l, m, coef = myData.k2lm(k) 

97 # k : integer index 

98 # 

99 # returns : 

100 # l (equivalent to n in other notations) : integer 

101 # m : integer 

102 # coef : 

103 # "g" or "h" for GHData 

104 # "tc", "ts", "sc", or "ss" for TSData 

105 

106 

107.. _GHData: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.GHData.html 

108.. _TSData: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.TSData.html 

109.. _MeasureData: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.measuredata.html 

110.. _normPnm: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.normPnm.html 

111.. _semiNormalisedSchmidt: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.normPnm.html#webgeodyn.data.normPnm.semiNormalisedSchmidt 

112.. _noNorm: https://geodynamo.gricad-pages.univ-grenoble-alpes.fr/webgeodyn/webgeodyn.data.normPnm.html#webgeodyn.data.normPnm.noNorm 

113 

114""" 

115 

116from .TSData import TSData 

117from .GHData import GHData