Configuration files
Format
pygeodyn configuration files are simply text files with .conf
extension where each line describes an input parameter of the computation. The format of these lines is quite simple:
name_of_the_parameter type value
In words: first, the name of the parameter (see below for the list), then the type (int for an integer, str for a string…) and finally the value, all separated by a space.
If a parameter is not set in the configuration file, the default value will be used (warning: some parameters are mandatory).
List of possible parameters
- Lb
Maximal spherical harmonic degree of the magnetic field.
Type: int
Default value: None (must be given)
- Lu
Maximal spherical harmonic degree of the core flow.
Type: int
Default value: None (must be given)
- Lsv
Maximal spherical harmonic degree of the secular variation.
Type: int
Default value: None (must be given)
- Ly
Maximal spherical harmonic degree of the constraint on the shear. Only used if
-shear
is 1.Type: int
Default value: None (must be given)
- Nth_legendre
Number of angles to use for the evaluation of Legendre polynomials.
Reducing this value can speed up computations but at the cost of numerical precision. It is therefore advised to leave it at its default value.
Type: int
Default value: 64
- t_start_analysis
Starting analysis time for the algorithm.
Type: float (decimal year)
Default value: None (must be given)
- t_end_analysis
Ending analysis time for the algorithm.
Type: float (decimal year)
Default value: None (must be given)
- N_dta_start_forecast
Starting forecast N x dta before
t_start_analysis
. N must be greater or equal to 1.Type: int
Default value: 1
- N_dta_end_forecast
Ending forecast N x dta after
t_end_analysis
.Type: int
Default value: 1 if AR3, 0 if AR1 or diag
- dt_f
Timestep between two forecast steps.
Type: float (decimal year)
Default value: None (must be given)
- dt_a_f_ratio
Number of forecasts per analysis.
dt_a_f_ratio = dt_analysis / dt_forecast
Type: int
Default value: None (must be given)
- AR_type
Type of Auto-Regressive (AR) process to use in forecasts. The possible values are diag (for diagonal AR-1), AR1 (for dense AR-1) and AR3 (for dense AR-3)
Type: str
Default value: diag
- combined_U_ER_forecast
Controls if we consider U and ER independant (0) or not (1) in the AR process (forecast).
We advise to keep U and ER independant (0) since combining U and ER for the AR process gives less stable results.
Type: int
Default value: 0
- TauU
Time constant for the core flow diagonal AR-1, given in number of months or years. Only used if AR_type was set to diag.
Type: months or years
Default value: 30 years
- TauE
Time constant for the subgrid errors diagonal AR-1, given in number of months or years. Only used if AR_type was set to diag.
Type: months or years
Default value: 10 years
- TauG
Galvanic time, given in number of months or years. Only used if
-shear
is 1.Type: months or years
Default value: 20 years
- dt_sampling
Apply a subsampling to the prior according to dt_sampling. Used only for the AR1 process.
Type: float (decimal year)
Default value: 5
- dt_smoothing
Duration of a blackman smoothing window applied to the prior. Used only for the AR3 process.
Type: float (decimal year)
Default value: 3.2
- N_pca_u
The algorithm can work with a Principal Component Analysis (PCA) of the core flow rather than on the core flow itself. It reduces the number of coefficients to compute and therefore the computation time. This parameter sets the number of components to use.
If in doubt, leave this untouched.
Type: int
Default value: 0 (no PCA performed)
- pca_norm
Normalisation to use when performing the PCA. Only used if N_pca is different from 0. The supported values are None and energy. With None, the PCA is performed directly on the Gauss coefficients of the core flow. With energy, the PCA is performed so that it is normalised with respect to energy (details in Gillet et al. 2019). This has only a minimal impact on the final result.
Type: str
Default value: None (as a string)
- core_state_init
Method to use to generate the initial core state (at the first time). The possible values are normal, and from_file.
With normal, the inital core state values for B, U, E, SV are initialised from priors. The realisations are generated from a normal draw around the prior background values with normal.
With from_file, the complete initial core state is the core state of a given file at a given date.
Type: str
Default value: normal
- out_analysis
Add the analysed states to the output hdf5 file. The possible values are 0 (not output) and 1 (output).
Type: int
Default value: 1
- out_forecast
Add the forecast states to the output hdf5 file. The possible values are 0 (not output) and 1 (output).
Type: int
Default value: 0
- out_computed
Add the computed states (analysis and forecast) to the output hdf5 file. The possible values are 0 (not output) and 1 (output).
Type: int
Default value: 0
- out_misfits
Add the misfits to the output hdf5 file. The possible values are 0 (not output) and 1 (output).
Type: int
Default value: 0
- out_format
Controls the format of the output hdf5 file. The possible values are float32 (single precision) and float64 (double precision).
Type: str
Default value: float32
- init_file
File to use for the core state initialisation. Only used if core_state_init is set to from_file.
Must be a valid path pointing towards a valid pygeodyn file.
Type: str
Default value: None (must be given if core_state_init is set to from_file)
- init_date
Date to use for the core state initialisation. Only used if core_state_init is set to from_file.
Must be an analysis decimal year time contained in the pygeodyn file given in init_file.
Type: float
Default value: None (must be given if core_state_init is set to from_file)
- prior_dir
Directory containing the prior data.
This directory should contain magnetic field, core flow and subgrid errors data that will be used to derive the correlation matrices used in the data assimiliation steps.
The given path can be absolute or relative to the configuration file.
Type: str
Default value: ./data/priors/71path
- prior_dir_shear
Directory containing the prior data for the shear computation. Only used if
-shear
is 1.This directory should contain the core flow and the error of representativeness for the shear that will be used to derive the correlation matrices used in the shear computation.
The given path can be absolute or relative to the configuration file.
Type: str
Default value:
prior_dir
- prior_type
Type of the prior data contained in
prior_dir
. Must correspond to a reading method implemented in pygeodyn/inout/priors.The supplied prior types are 0path and 50path, 71path and 100path that are results of free runs of the eponymous geodynamo simulations by J. Aubert ([AFF13] and [AGF17]).
Type: str
Default value: 71path
- prior_type_shear
Type of the prior data contained in
prior_dir_shear
. Only used if-shear
is 1.Must correspond to a reading method implemented in pygeodyn/inout/priors.
The supplied prior types are 0path and 50path, 71path and 100path that are results of free runs of the eponymous geodynamo simulations by J. Aubert ([AFF13] and [AGF17]).
Type: str
Default value:
prior_type
- obs_dir
Directory containing the observation data. This directory should contain magnetic and secular variation data (measurements and errors) that will be used in the estimations performed in analysis steps.
The given path can be absolute or relative to the configuration file.
Type: str
Default value: ./data/observations/COVOBS-x2_maglat
- obs_type
Type of the observation data contained in obs_dir. Must correspond to a reading method implemented in pygeodyn/inout/observations.
The supplied observation types can be - COVOBS, a stochastic model from [GJF13] (extended in [GBF15]), - COVOBS_hdf5, a more recent version of the stochastic model COVOBS, - chaos_hdf5, an estimation of earth magnetic field using ground observatory and satellite data (SWARM and CHAMP missions) - GO_VO, measurements of Ground Observatories and preprocessed satellite data (CHAMP, Swarm, Oersted, Cryosat and composite) under the form of Virtual Observatories spread all around the globe ([BHF18], [Hammer18]).
Type: str
Default value: COVOBS_hdf5
- SW_err
Used if obs_type is GO_VO. Specify if we consider SWARM diagonal or dense error matrix R. ONLY APPLY IF SWARM 4MONTHS DATA!!!
Type: str
Default value: diag
- remove_spurious
The graphical Lasso parameter.
- Dictate how the covariance matrix in the Kalman gain will be approximated. Big values will approximate the covariance matrix by its diagonal or almost diagonal and small values will result in a covariance matrix still close to the empirical estimate of the covariance.
In practise a parameter bigger than 1 will always return a diagonal matrix.
For the AR1, a good value can be estimated as \(\frac{35}{N}\), with N the number of realisations [IGF23].
Default value will result in a diagonal covariance matrix. If it does not converge, try a larger value.
Type: float
Default value: np.inf
- remove_spurious_shear_u
The graphical Lasso parameter. Only used if
-shear
is 1.- Dictate how the core flow covariance matrix will be approximated. Big values will approximate the covariance matrix by its diagonal or almost diagonal and small values will result in a covariance matrix still close to the empirical estimate of the covariance.
In practise a parameter bigger than 1 will always return a diagonal matrix.
Default value will result in a diagonal covariance matrix. If it does not converge, try a larger value.
Type: float
Default value: np.inf
- remove_spurious_shear_err
The graphical Lasso parameter. Only used if
-shear
is 1.- Dictate how the error of representativeness covariance matrix will be approximated. Big values will approximate the covariance matrix by its diagonal or almost diagonal and small values will result in a covariance matrix still close to the empirical estimate of the covariance.
In practise a parameter bigger than 1 will always return a diagonal matrix.
Default value will result in a diagonal covariance matrix. If it does not converge, try a larger value.
Type: float
Default value: np.inf
- obs_select
Only if obs_type is equal to GO_VO. Dictionnary that defines the selection of ground and virtual observatories data used in the algorithm. For instance, to use the secular variation (SV) of the ground obsertories and both the magnetic field (MF) and the SV for the CHAMP satellite, define “obs_select dict {‘GROUND’:’SV’, ‘CHAMP’:(‘MF’, ‘SV’)}”. Possible observatories are GROUND, CHAMP, SWARM, OERSTED, CRYOSAT and COMPOSITE, and corresponding files name should start with GO, CH, SW, OR, CR or CO.
Default value will search for all available data in folder except COMPOSITE
Type: dict
Default value: all
- discard_high_lat
All observations that are located at a geomagnetic latitude higher than the value of discard_high_lat will not be taken into account. Inclination of the dipole is computed using the first three Gauss coefficients from Chaos 7 data at the closest time from the observations. The default value is 0 which means no observations will be discarded.
Type: float
Default value: 0
- obs_mod_errors_dir
Warning
This has not been throughly tested ! Use only if you really need to and you know what you are doing !
Directory containing modelisation errors for the magnetic field (MF.err) and the secular variation (SV.err). The files must exist and have store errors for Nb coefficients for MF and Nsv for SV.
This allows to add constant errors to observations of type COVOBS_hdf5.
Type: str
Default value: None
References
Aubert, J., Finlay, C. C. & Fournier, A. Bottom-up control of geomagnetic secular variation by the Earth’s inner core, Nature, 502, 219–223, 2013. doi:10.1038/nature12574
Aubert, J., Gastine, T. & Fournier, A. Spherical convective dynamos in the rapidly rotating asymptotic regime, Journal of Fluid Mechanics, 813, 558–593, 2017. doi:10.1017/jfm.2016.789
Barrois, O., Gillet, N., & Aubert, J. Contributions to the geomagnetic secular variation from a reanalysis of core surface dynamics, Geophysical Journal International, 211(1), 50-68, 2017. doi:10.1093/gji/ggx280
Barrois, O., Hammer, M. D., Finlay, C. C., Martin, Y. & Gillet, N. Assimilation of ground and satellite magnetic measurements: inference of core surface magnetic and velocity field changes, Geophysical Journal International, 2018. doi:10.1093/gji/ggy297
Gillet, N., Barrois, O. & Finlay, C. C. Stochastic forecasting of the geomagnetic field from the COV-OBS.x1 geomagnetic field model, and candidate models for IGRF-12, Earth, Planets and Space, 67, 2015. doi:10.1186/s40623-015-0225-z
Gillet, N., Huder, L., & Aubert, J. A reduced stochastic model of core surface dynamics based on geodynamo simulations, Geophysical Journal International, 219(1), 522-539, 2019. doi:10.1093/gji/ggz313
Gillet, N., Jault, D., Finlay, C. C. & Olsen, N. Stochastic modeling of the Earth’s magnetic field: Inversion for covariances over the observatory era, Geochemistry, Geophysics, Geosystems, 14, 766–786, 2013. doi:10.1002/ggge.20041
Hammer, M. D. Local Estimation of the Earth’s Core Magnetic Field. (Technical University of Denmark (DTU), 2018).
Istas, M., Gillet, N., Finlay, C. C., Hammer, M. D., & Huder, L. Transient core surface dynamics from ground and satellite geomagnetic data, Geophysical Journal International, 233, 1890–1915, 2023. doi:10.1093/gji/ggad039