The initial version of MESMER was developed to generate large ensembles of spatially resolved annual mean daily land surface air temperature (“tas”) time series that mimic ESM output . Subsequently, the MESMER ecosystem grew, adding more capabilities: MESMER-M extends the emulator to monthly local temperatures . Similarly, MESMER-M-TP emulates monthly local temperature and precipitation . Lastly, MESMER-X introduced capabilities to emulate various annual indicators of climate extremes and climate impact drivers, such as the annual maximum of daily maximum land surface air temperature (“txx”) or soil moisture . Despite using different statistical methods, each approach separates the local signal into a local response and local variability, providing a common ground for the design of MESMER v1. In the next sections we will shortly discuss the (statistical) methods used for each of these MESMER components.

The emulation of spatially resolved annual mean land surface air temperatures consists of two main modules: (1) the local response module, which translates the global mean temperature into the local temperature response on a gridcell level using linear regression. (2) The local residual variability module generates temporally and spatially correlated random samples, with an order 1 auto-regressive (AR(1)) process and spatially correlated innovations. To dampen spurious correlations from rank deficient empirical covariance matrices, a Gaspari-Cohn localization is employed (see Table , and ). We refer to the state of the MESMER code base before the rewrite as the original MESMER version MESMER v0.8.3 in, corresponding to the release for .

MESMER-M is the monthly emulation component of MESMER. It takes in gridded local annual mean temperature and emulates gridded local monthly temperature. MESMER-M relates the annual mean temperature at each gridcell to its monthly temperature response using a harmonic model. To make potentially skewed residuals more normal a Yeo-Yohnson Power Transformer is employed. The residual variability module emulates spatially and temporally correlated noise for each month, employing a cyclo-stationary AR(1) process . The same approach is used to localize the empirical covariance matrix as in the original MESMER. The details of the method are presented in and outlined in Table .

MESMER-M-TP is a monthly precipitation extension to MESMER-M . It generates gridded monthly mean precipitation fields using gridded monthly mean temperature fields as input. The emulator is designed to realistically capture the covariance structure between temperature and precipitation, ensuring that the generated precipitation fields are spatially and temporally consistent with the input temperature fields. Precipitation at each gridcell and for each individual month is modeled as the product of two components: The first component describes how precipitation statistically co-varies with temperature, modeled with a Generalized Linear Model, specifically with a gamma distribution with a logarithmic link. Here, temperatures from neighboring gridcells (within a configurable radius) serve as predictors for local precipitation responses. The second component accounts for variability in precipitation not explained by temperature. While assumed temperature-independent, this residual term can still reflect spatial correlations across the precipitation field. To capture this structure, the residuals are transformed via principal component analysis (PCA), and their distribution is estimated using kernel density estimation with a Gaussian kernel for resampling (Table ).

We note that MESMER-M-TP is not fully integrated in MESMER v1, but we include it here for completeness. The full integration of MESMER-M-TP is expected to follow in the next MESMER release.

MESMER-X was developed to emulate local climate extremes and climate impact drivers . Instead of a local response module as employed in MESMER it uses non-stationary distributions, i.e. distributions of the climate variable that are conditional on covariates, e.g., the global mean temperature. Therefore it can accommodate non-normal distributions and non-linear responses to changes in global climate. This module is designed to be applicable for a large range of variables, thus allows various distributions (Normal, Generalized Extreme Value, etc.) and covariate responses (linear, polynomial, sigmoid, etc.). The generation of realizations is achieved by sampling an AR(1) process as in MESMER, and subsequently using Probability Integral Transforms to transform the drawn samples to the distributions of the climate indicators (Table ).

Previously, the individual MESMER components listed above were published in separate repositories, or, in the case of MESMER-X, not accessible to the public at all. Overall, there was no overarching software architecture. While all components were written in Python, the structure varied across components. Some components were written in an object-oriented style, others were a collection of scripts that had to be executed in the right order, and others were collections of function definitions and execution code in single Jupyter Notebooks. Across all four components, there were about 12 000 lines of code in 60 files.

External documentation for MESMER-M, MESMER-M-TP and MESMER-X was limited to the model description papers , whereas MESMER already had a documentation webpage with an API reference. Around 60 % of public function and class definitions were documented with docstrings in the legacy code. The code quality of the legacy components was mixed, scoring pylint scores between 0 and 8.03, were 0 is the smallest (worst) score possible and 10 the highest (best).

The comprehensibility of the software was further hampered by a rather in-transparent data structure consisting of nested dictionaries, where data was stored as plain numpy arrays . To navigate the data one had to know the dictionary structure, the appropriate keys, and data dimensions. Lastly, MESMER-M, MESMER-M-TP and MESMER-X had no testing suite, ensuring correctness and stability of the code. As of the release of MESMER v0.8.3 in , MESMER had a test coverage of around 78 %.

MESMER v1 is a pure python package and contains statistical functionality and utilities to process ESM data to be used in the statistical functions. The statistical functions and classes are organized in two modules: mesmer.stats, and mesmer.distrib (Fig. ). The module mesmer.distrib holds classes and functions related to conditional probability distributions, i.e., functionality that is mainly used in MESMER-X such as fitting a conditional distribution (mesmer.distrib. ConditionalDistribtion().fit) or the probability integral transform (mesmer.distrib.Probability

IntegralTransform). The module mesmer.stats contains all other statistical classes and functions, including linear regression (mesmer.stats.LinearRegression), auto-regression (e.g., mesmer.stats.select_ar_order), and others. The data handling functionality is distributed over several modules, and includes functions to compute anomalies (mesmer.anomaly.calc_anomaly), the global mean (mesmer.weighted.global_mean), or for pooling data of several scenarios and ensemble members of ESM runs (mesmer.datatree.pool_scen_ens).

This layout leads to the following new workflow for the user: for calibrating MESMER they need to (1) load the predictor data, (2) calibrate the parameters using the statistical functionalities and (3) save the parameters. To create emulations, users need to (1) load the ESM-specific parameters again, (2) calculate the (deterministic) local response, (3) draw samples of the local variability, and (4) save the emulations. This workflow is demonstrated in the tutorials delivered with MESMER and on the documentation webpage. The restructured workflow is more in line with the framework shown in Fig. . It allows users to interact with the statistical methods directly, and every step of the computation is clearly separated. It disentangles the data handling from the statistical functionality, and the data loading and saving, and organizes the code into small units only concerned with one well-defined task, making the code more modular .

MESMER v1 uses a new data structure based on xarray . xarray provides multi-dimensional labeled arrays and datasets in Python. It adopts Unidata’s self-describing Common Data Model on which the network Common Data Form (netCDF) is built. One main advantage over the previously-used numpy array manipulation library is the introduction of labeled array dimensions, as well as providing coordinates to these named dimensions and adding attributes to arrays and datasets. This facilitates keeping track of multiple dimensions present in the climate data used in MESMER, e.g. latitude, longitude, time, or initial condition member. Several xarray arrays (xarray.DataArray) can be collected into Dataset objects in the form of named data variables if their coordinates align, e.g. they live on the same grid and have the same time steps. Several datasets in turn can be held in a so called DataTree, which allows for a hierarchical storage of data that lives on different coordinate systems.

MESMER was designed to be calibrated on ESM model output from the Coupled Model Intercomparison Projects (CMIP), e.g. CMIP6 . We combine historical simulations with future projections, such as the shared socioeconomic pathways (SSPs), . Most models provide several scenarios, and historical and future data do not have the same time coordinates. Therefore, different scenarios are stored in DataTree objects in MESMER. Predictor data for, e.g. global mean temperature (tas) and optionally squared global mean temperature (tas2) or global mean ocean heat content (hfds), are held in Datasets at each node of the tree (Fig. a). Similarly, the target variable for each scenario, e.g., gridded near surface air temperature, is stored in a separate DataTree object (Fig. b). Each variable in the datasets is a DataArray with a time dimension, and for the gridded data, an additional gridcell dimension. If several initial condition members are available for the same scenario, these can be stored along a member dimension. It is thereby important, that the predictor and target trees are isomorphic, i.e. they hold the same scenarios, and that in each scenario, the coordinates align, so that each target sample also has a corresponding sample in the predictor data. For several of the statistical routines, the data must be pooled into a single sample dimension, where scenario, time, and member dimensions are stacked into one (Fig. c and d). MESMER provides a routine for the pooling, ensuring that no missing values occur from incorrect stacking and predictor and target data are aligned (mesmer.datatree.broadcast_and_pool_scen_ens).

The adoption of xarray data structures allowed us to effortlessly save parameters as netCDF files, instead of the previously used pickle format. netCDF is a widely used scientific data format and has several advantages over pickle files in that it saves independent of the underlying python structures, which makes it more secure, interoperable with most common programming languages and ensures it can seamlessly be read in the future .

Together with MESMER v1 we publish pre-calibrated parameters for the emulation of multiple variables : annual mean air temperature, monthly mean air temperature, annual maximum air temperature, annual average of soil moisture, annual minimum of the monthly average soil moisture, annual maximum of the Fire Weather Index, seasonal average of the Fire Weather Index, annual number of days with extreme fire weather, and length of the fire season. For information on the Fire Weather Index please refer to . The parameters are calibrated for 58 CMIP6 models post-processed according to , using all available initial condition members of SSP1-1.9, SSP1-2.6, SSP2-4.5, SSP3-7.0, SSP4-6.0, SSP5-8.5, and SSP5-3.4-OS for each model. We calibrate using only global mean surface air temperature as a predictor. The pre-calibrated parameters allow users who are interested in emulations of the listed variables to omit the calibration step. We thereby establish a consistent parameter-set for future applications. This parameter-set will be maintained together with MESMER and can be extended depending on the interest of the research community.

To ensure that MESMER v1 is accessible to a broad range of users, we considerably extended the documentation of the software. We created a MESMER documentation webpage (https://mesmer-emulator.readthedocs.io/, last access: 26 June 2026, Fig. a), which is automatically generated for each version of the code to ensure it is always up-to-date. Highlights of the new documentation webpage include the API reference, which consists of the rendered in-code documentation of all public functions and classes (Fig. b), and multiple tutorials that demonstrate the workflow of the most important MESMER use-cases, therein calibrating on a real (but coarse resolution) example ESM and creating emulations for the given ESM, for the MESMER, MESMER-M and MESMER-X workflow (Fig. c). These tutorials are rendered from interactive jupyter Notebooks, also available from the MESMER repository (see Figure caption for link) for users to download. Moreover, the documentation also contains the open software license of MESMER, notably the GNU General Public License as published by the Free Software Foundation, version 3 (cf. https://www.gnu.org/licenses/gpl-3.0.html, last access: 10 September 2025) and resources for developers.

In addition, the MESMER github page (https://github.com/MESMER-group/mesmer, last access: 25 June 2026) provides development oriented documentation. Here, the development team records all changes made to the software, discusses its design, collects issues, and structures the development workflow. In addition, this page is an access point for users to post issues or calls for improvement.

Re-structuring the MESMER code into small units allowed us to write extensive unit tests, which ensure each individual function and method works as expected. We make use of two kinds of tests in MESMER v1: unit tests and integration tests. Unit tests are used to test the smallest units of code in a program (i.e. a single function or method), while integration tests ensure that these units work as intended when combined . The test suite of MESMER is automatically run every time a contribution is made to the MESMER code base on github, and can of course also be run locally by the developer.

The implemented unit tests include testing that errors are raised when expected, return values are of the expected type or shape, and class attributes are assigned as expected. More sophisticated unit tests test that an API fulfills its intended purpose. Such tests in MESMER v1 are for example if the fitting routine of the auto-regressive process or the linear regression can retrieve the correct parameters from simulated data with known parameters, or if the Yeo-Johnson Power Transformer actually reduces the skew of artificially skewed data.

While each MESMER component (MESMER, MESMER-M, MESMER-X) showed good performance in emulating the statistical properties of ESM output , no integration tests were available for MESMER-M and MESMER-X. Therefore, the integration tests of MESMER v1 execute the whole calibration and emulation workflow for each MESMER component. Specifically, each component is calibrated using CMIP6 data that was re-gridded to a coarse resolution of 20×20 gridcells. Subsequently, one to ten realizations are drawn using the calibrated parameters. The calibrated parameters and emulations are compared to previously-saved output. This ensures stability of MESMER functionality as well as the numeric stability over time, or between different machines. The latter is especially important for software that is used in a scientific context to ensure reproducibility . If a change is intended, the developer can update the saved test data.

We assess if MESMER v1 reaches the development goals (1) modular and comprehensible source code, (2) modern data structure, (3) internal and external documentation, (4) test coverage of the whole project, and (5) strategy for version control and continuous integration. We exclude tests, tutorials, documentation source files, and deprecated modules from the assessment, as well as the testing module, which is only thought for use in the tests.

Previous versions of MESMER produced numerically different emulations on different machines, despite using the exact same parameters. We traced this problem back to numerical instabilities in the inversion of the spatial covariance matrix and were able to resolve it by changing the decomposition strategy of the spatial covariance matrix from a singular value decomposition to the Cholesky method . The decomposition is needed to sample tempo-spatially correlated variability at each gridcell, i.e. the white noise term of the AR(1) process (Fig. c). While the decomposition using singular value decomposition is not unique and depends on linear algebra routines independent of the python installation on a machine, Cholesky decomposition is unique and produces stable results on different machines (see also https://numpy.org/doc/2.3/reference/random/generated/numpy.random.Generator.multivariate_normal.html, last access: 10 September 2025). We find that Cholesky decomposition is about 80–100 times faster for a 118×118 matrix than singular value decomposition. Consequently, using the Cholesky method has the added benefit of speeding up the calibration (7.8 times faster) and emulations (1.7 times faster). The calibration step sees a bigger improvement because the covariance matrix needs to be transformed several times during the cross-validation step (15 cross-validations for 7 radii with our test data).

Additionally, we want to note that large localization radii can lead to singular localizer matrices and are thus not suited for mitigating spurious correlations in the empirical covariance matrix. This phenomenon starts occurring at localization radii of about 11 000 km and larger. Such large localization radii are only rarely selected by the cross-validation, except when there are a large number of samples, e.g. a large number of initial condition members, are available, in which case the rank deficiency of the empirical covariance matrix is small. In such cases, the large localization radius must be kept sufficiently low to preserve a positive definite covariance matrix, thus still mitigating spurious correlations.

We were able to reduce the time needed for the fit of the harmonic model from about 4 min to below one second for our test dataset. First, we only fit the Fourier Series up to an order of 6 instead of 12 by default, since a Fourier series of order 6 is able to capture a series with 12 features. Second, we now only fit until the first local minimum of the Bayesian Information Criterion is reached when finding the optimal order, as the BIC was found to increase monotonically thereafter. Third, we pass the parameters from the previous order as first guess when fitting the parameters of the Fourier Series for each new order. This improves the performance since the parameters of the lower order terms only vary slightly when adding a new order to the series. We also optimized the generation of the Fourier Series by factoring out constant terms, e.g. the harmonic representation of the months.

Testing the Power Transformer showed that it did not reliably reduce the skew of monthly residuals. We stabilized the Power Transformer by expanding the bounds imposed on the optimization of the parameters of the logistic function used for conditioning the normalization parameter, and switched the optimization method to Nelder-Mead. Moreover, we set the first guess for the fitting to assume the data is already normally distributed, which has proven to be a good first guess for the monthly temperature residuals. In addition, there were problems with the numerical stability of the back-transformation using the Power Transformer, that arose from floating point errors in the formulation of the transform. Specifically, round-tripping certain values did not lead to the original data for small numbers. We were able to fix these issues by switching to more precise numpy routines in the computation of the transformed data (namely numpy.expm1(x) and numpy.log1p(x) which yield higher precision for small x than numpy.exp(x)-1 and numpy.log(1+x), cf. https://numpy.org/doc/stable/reference/generated/numpy.expm1.html, last accessed: 12 March 2026). With these adjustments, the time needed for the calibration of the Power Transformer was reduced from approximately 8 min to under 5 s.

The method employed to emulate local variability for monthly temperatures is different from the approach for annual temperatures . The residual temperature variability of June may depend differently on the one of May than the one of July does on June. Therefore, there are separate AR parameters for each calendar month, and the method used for monthly temperature emulations is a cyclo-stationary AR(1) process instead of a AR(1) process . In contrast to the AR(1) process, a cyclo-stationary AR(1) process can still be stationary with AR-coefficients larger than absolute 1, since the destabilizing effect of one coefficient (e.g. of one month) can be compensated by another (e.g. the one of the next month). We thus removed the bounds of [-1, 1] enforced on the slopes during the fitting routine of the monthly AR(1) process and found that slopes outside these bounds do appear in our parameters. Consequently, we are not able to adjust the covariance matrix with the AR slopes anymore as done for e.g. annual mean temperatures . To prevent the overestimation of the driving noise variance, we now fit the covariance matrix on the residuals of the cyclo-stationary AR(1) process and found that for generated data, this leads to a better representation of the variability than estimated by the AR(1) process (Fig. ).

MESMER-X emulates climate variables by sampling their values from a calibrated conditional distribution. Thereby, every parameter of the conditional distribution, e.g. the location or the scale, can be a function of covariates, i.e. global predictors such as the change in global mean temperature. Both the type of distribution and the functions for the parameters are chosen by the user, based on statistical and physical arguments. Identifying the adequate distribution and functions require data exploration and validation (see ). Because MESMER-X is designed to be able to emulate a large range of variables, the module to train these conditional distributions is designed for flexibility and robustness of the training. To maximize the chances of finding the best solution, an algorithm finds a first guess, as close as possible to the final solution. This algorithm builds on the principles introduced in , which uses an iterative process to fine tune the first guess for each gridcell:

First approximation for the location: using only the function of the location, global minimization of the square of the errors on the mean of the sample and the first derivatives with the predictors.

The global optimizer is a Basinhopping algorithm, with 10 iterations and 100 intervals, with a seed set for reproducibility. The local optimizer is a Nelder-Mead algorithm, but the user may provide a second local optimizer, and the best result will be used. When minimizing the negative log-likelihood, weights can be used for every point of the sample, e.g. uniform or based on the density of the predictor samples. The predictor samples are often not equally distributed over their whole range, for example the global mean temperature has more samples at lower than high values because there is a longer period of relatively constant temperatures in the historical period. Therefore, a weighting may help in providing equal performance for the fit over the whole range of the predictors. This weighting is based on the inverse of the density, calculated with a Gaussian kernel-density estimate.

The solution for the conditional distribution is finally obtained by a local minimization of the negative log-likelihood from this first guess, accounting for given weights. Every iteration during the minimization is checked with the same tests outlined in step 5 of the first guess. The optimizer is again Nelder-Mead, with the possibility to use a second one defined by the user. Overall, the first guess module enhances the chances of finding a good fit of the conditional distribution.