# MONARCHS run settings This provides a reference for all of the possible settings available in the model. It is automatically generated from the variables in the settings catalogue (`monarchs.config.catalogue`). If you add more settings, these will be automatically added here provided you have added them to the catalogue itself. ## Grid ### `row_amount` **Type:** int  ·  **Default:** **required** Number of rows (i.e. ``y``-points) in your model grid, looking from top-down. MONARCHS indexes the model grid via ``grid[col][row]``, i.e. the ``y``-coordinate is the second index. This has only been tested with the same # of points as ``col_amount``, so use caution if using different values for each of these. ### `col_amount` **Type:** int  ·  **Default:** **required** Number of columns (i.e. `x`-points) in your model grid, looking from top-down. MONARCHS indexes the model grid via ``grid[col][row]``, i.e. the ``x``-coordinate is the first index. This has only been tested with the same # of points as ``row_amount``, so use caution if using different values for each of these. ### `vertical_points_firn` **Type:** int  ·  **Default:** **required** Number of vertical grid cells in the firn profile. Default is 400. This determines the resolution of the model vertically. For best results ensure that your vertical resolution is on the order of ~10 cm (i.e. your maximum firn height divided by ``vertical_points_firn`` is approximately 0.1) ### `vertical_points_lake` **Type:** int  ·  **Default:** **required** Number of vertical grid cells in the lake profile. Default 20, as lakes are both much smaller than the firn column and less sensitive to vertical resolution since they are turbulently mixed. ### `vertical_points_lid` **Type:** int  ·  **Default:** **required** Number of vertical grid cells in the lid profile. Default 20. ### `lat_grid_size` **Type:** str or float  ·  **Default:** 'dem' when a DEM is provided Size of each grid cell in m, if a DEM is provided. ## Timestepping ### `num_days` **Type:** int  ·  **Default:** **required** Number of days (i.e. full model iterations) to run for. A day is ``t_steps_per_day`` steps of the single-column physics, followed by one pass of the lateral flow algorithm. ### `t_steps_per_day` **Type:** int  ·  **Default:** `24` Number of timesteps to run for each day. 24 = 1h resolution, 8 = 3h resolution, etc. ### `lateral_timestep` **Type:** int  ·  **Default:** model_setup.t_steps_per_day * 3600 Timestep for each iteration of lateral water flow calculation (in s). It is highly unlikely this should be anything other than 3600 * 24. ## DEM ### `latmax` **Type:** float  ·  **Default:** `nan` ### `latmin` **Type:** float  ·  **Default:** `nan` ### `longmax` **Type:** float  ·  **Default:** `nan` ### `longmin` **Type:** float  ·  **Default:** `nan` ### `bbox_top_right` **Type:** list  ·  **Default:** `False` Corner of a bounding box constraining the model domain, given as ``[lat, long]``. Set all four corners to run on a subset of a large DEM. With ``lat_bounds == 'dem'`` the input met data is regridded to these bounds. (i.e. the met data shifts with the choices made here). ### `bbox_bottom_left` **Type:** list  ·  **Default:** `False` Corner of the model bounding box - see ``bbox_top_right``. ### `bbox_top_left` **Type:** list  ·  **Default:** `False` Corner of the model bounding box - see ``bbox_top_right``. ### `bbox_bottom_right` **Type:** list  ·  **Default:** `False` Corner of the model bounding box - see ``bbox_top_right``. ### `input_crs` **Type:** int  ·  **Default:** `3031` ### `firn_max_height` **Type:** float  ·  **Default:** `150` Maximum height that your firn column can be at. Use this if you're loading in a DEM which has large height ranges. ### `firn_min_height` **Type:** float  ·  **Default:** `20` Minimum height that we consider to be "firn". Anything below this we consider to be solid ice, which affects some of the physics. ### `max_height_handler` **Type:** str  ·  **Default:** `'filter'` How to handle cells that exceed ``firn_max_height``, designed to help us filter out land cells. ``'filter'`` sets ``cell.valid_cell = False``, so no physics is run on the cell and it stays the same throughout the model. ``'clip'`` caps those cells at ``firn_max_height`` and keeps running physics on them. ### `min_height_handler` **Type:** str  ·  **Default:** `'filter'` Handle regions on a DEM below the specified minimum height. Possible options are ``'extend'`` (add height to all cells to bring the lowest area up to the minimum), ``'normalise'`` (keep heights as-is, adjust density to account for the lower height), ``'filter'`` (set the cells invalid so physics doesn't run), and ``'clip'`` (bring everything up to the minimum without keeping the relative values). ### `dem_diagnostic_plots` **Type:** bool  ·  **Default:** `False` If ``True``, generate some plots to check that we have read in the DEM correctly. This is useful if using a bounding box to select a subset of the original DEM, so you can check visually that it is working as intended. ### `DEM_path` **Type:** str  ·  **Default:** optional (unset) Path to a digital elevation model (DEM) to be read in by MONARCHS, according to its filetype and interpolated to shape ``(row_amount, col_amount)``. Provide this or ``firn_depth``. If using a relative path, it is relative to the folder you are running MONARCHS from, not the folder that the code repository is included in - e.g. if your DEM is in ``/home/data/DEM/test_dem.tif`` and you run MONARCHS from ``/home/model_runs/test_run``, the DEM path would be ``'../../data/DEM/test_dem.tif'``. ### `lat_bounds` **Type:** str  ·  **Default:** optional (unset)  ·  **Allowed:** `dem` Toggle whether to constrain the input met data file to lat/long bounds specified by a digital elevation model (DEM) or not. If set to ``'dem'``, then the model grid and input meteorological data are constrained to the lat/long of the DEM, i.e. the data from the met data netCDF is matched/regridded to the DEM, accounting for changes in e.g. the coordinate reference systems between the two. See ``examples/50x50_numba_parallel`` for an example, which has ``met_dem_diagnostic_plots == True`` so a plot is generated showing what this does visually. ## Initial conditions ### `rho_init` **Type:** str or float  ·  **Default:** `'default'` Initial density profile. This follows Paterson, W. (2000). The Physics of Glaciers. Butterworth-Heinemann, using the formula of *Schytt, V. (1958). Glaciology. Norwegian-British-Swedish Antarctic Expedition, 1949-5, IV*. With 'default', MONARCHS calculates an empirical density profile with ``rho_sfc`` = ``500`` and ``z_t`` = ``37``. Alternatively, specify either a) a pair of points in the form ``[rho_sfc, zt]`` to use this equation and specify ``rho_sfc`` and ``z_t`` yourself, b) a 1D array of length ``vertical_points_firn`` to specify a uniform density profile across the whole grid, or c) an array of dimension(``row_amount``, ``col_amount``, ``vertical_points_firn``) to specify different density profiles across your model grid. ### `T_init` **Type:** str or float  ·  **Default:** `'default'` Initial temperature profile. With 'default', MONARCHS uses an assumed firn top temperature of 260 K and bottom temperature of 240 K, linearly interpolated between these points. Alternatively, specify either a) a pair of points in the form [top, bottom] to assume a linear temperature profile across the whole grid, b) a 1D array of length ``vertical_points_firn`` to specify a uniform temperature profile across the whole grid, or c) an array of dimension(``row_amount``, ``col_amount``, ``vertical_points_firn``) to specify different temperature profiles across your model grid. ### `rho_sfc` **Type:** float  ·  **Default:** `500` Initial surface density used to calculate the profile if using ``rho_init`` = 'default'. Defaults to 500. ### `firn_depth` **Type:** float  ·  **Default:** optional (unset) Initial depth of the firn columns making up the MONARCHS model grid. Provide this or ``DEM_path`` - **if a valid DEM path is specified, then this is overridden by the DEM**. Specify as either a number, assumed as the firn depth across the whole grid, or an array of dimension(``row_amount``, ``col_amount``) giving the firn depth across the whole grid.e.g. ``gaussian_testcase.export_gaussian_dem`` in the ``10x10_gaussian_threelake`` example generates a usable Gaussian three-lake profile. ### `initial_conditions` **Type:** dict  ·  **Default:** optional (unset) Optional {grid variable: value} overrides applied when building the initial grid, e.g. {'lake_depth': 0.5}. Keys must be names from the variable catalogue (monarchs.variables), with appropriate values (scalar or array depending on the field). ## Forcing ### `met_data_source` **Type:** str  ·  **Default:** inferred from the input given  ·  **Allowed:** `ERA5`, `user_defined` Format of the meteorological forcing. Depending on the source, the met data will be set up from the corresponding data input - e.g. an ERA5 forcing file if 'era5' is specified - see ``monarchs.met_data.sources``. If you do not set this, it is inferred from whichever input you provide - ``met_input_filepath`` gives 'ERA5', ``met_data`` gives 'user_defined'. ### `met_timestep` **Type:** str  ·  **Default:** `'hourly'` Temporal resolution of your input meteorological data. Ideally, MONARCHS would read in hourly gridded data. However, it is possible that the user may want to run long climate simulation runs, which may necessitate lower temporal resolution. If str, the value should be 'hourly', 'three-hourly' or 'daily'. For other resolutions, please specify an integer, corresponding to how many hours each point in your data corresponds to - 'hourly' is 1, 'three_hourly' is 3, and 'daily' is 24. ### `met_output_filepath` **Type:** str  ·  **Default:** `'interpolated_met_data.nc'` Filepath for the interpolated grid used by MONARCHS to be saved. This is used to save memory, and prevent us from having to repeatedly interpolate our input data. This file can be large if running for large domains and timescales. Therefore,this setting is useful for those who e.g. want to save this file into scratch space rather than locally. ### `met_dem_diagnostic_plots` **Type:** bool  ·  **Default:** `False` If ``True``, generate some plots to show the regridding of the meteorological data onto the DEM lat/long grid. Useful as a sanity check to make sure that this has worked as intended. Typically you might run a test (in serial, on a local machine) where you cancel the run during the first model day to check these plots, then re-run (in parallel, possibly on HPC) with this set to ``False``. ### `load_precalculated_met_data` **Type:** bool  ·  **Default:** `False` ### `met_input_filepath` **Type:** str  ·  **Default:** optional (unset) Path to a file of meteorological data to be used as a driver to MONARCHS. Provide this or ``met_data``. At the moment, only ERA5 format (in netCDF) is supported. If this is a relative filepath, then you should ensure that is relative to the folder in which you are running MONARCHS from, not the source code directory. ### `met_data` **Type:** dict  ·  **Default:** optional (unset) User-defined met data as a dict. Provide this or met_input_filepath. ### `radiation_forcing_factor` **Type:** float  ·  **Default:** `1` Multiply the shortwave/longwave radiation variables by this factor for testing purposes, e.g. if running a 1D case and you want to ensure that lake formation occurs. This is left in mostly as an example; see ``monarchs.met_data.setup_met_data.scale_by_factor`` for more details. ## Toggles ### `snowfall_toggle` **Type:** bool  ·  **Default:** `True` Determines whether to add height to the firn column via snowfall over time, or not. e.g. can be turned off if you don't have a source of snowfall data. ### `firn_column_toggle` **Type:** bool  ·  **Default:** `True` Determines whether the firn column is allowed to evolve or not, i.e. if ``physics.firn_column`` is ever invoked. ### `firn_heat_toggle` **Type:** bool  ·  **Default:** `True` Determines whether the temperature of the firn is allowed to evolve, i.e. if ``physics.heateqn`` is ever invoked. ### `percolation_toggle` **Type:** bool  ·  **Default:** `True` Determines whether water can percolate during the firn column evolution step. ### `perc_time_toggle` **Type:** bool  ·  **Default:** `True` Determines if percolation occurs over timescales (if ``True``), or all water can percolate forever until it saturates a cell (as in the old MATLAB model). ### `lake_development_toggle` **Type:** bool  ·  **Default:** `True` Determines whether lakes are allowed to form, i.e. if ``physics.lake_development`` is ever invoked. ### `lid_development_toggle` **Type:** bool  ·  **Default:** `True` Determines whether frozen lids are allowed to form, i.e. if ``physics.lid_development`` is ever invoked. ### `lateral_movement_toggle` **Type:** bool  ·  **Default:** `True` Determines whether water can move between grid points laterally, or if we treat each column as entirely independent. ### `lateral_movement_percolation_toggle` **Type:** bool  ·  **Default:** `True` Determines whether water can percolate during the lateral movement step, assuming that ``lateral_movement_toggle`` is ``True``. ### `single_column_toggle` **Type:** bool  ·  **Default:** `True` ### `densification_toggle` **Type:** bool  ·  **Default:** `False` Determines whether snow densification is enabled. This is currently always False since our implementation of snow densification is WIP. ## Lateral ### `flow_into_land` **Type:** bool  ·  **Default:** `True` If ``True``, then similarly to ``catchment_outflow``, water that reaches the edge of the grid and is at a local minimum will flow out of the model if it is adjacent to a land cell. This is motivated by the presence of large lakes at the edge of the ice shelf in the validation runs, which are not seen in observational datasets. This occurs since the water has nowhere else to go, and thus a positive feedback loop occurs where the lake grows, melts the firn underneath, and more water flows in. ### `catchment_outflow` **Type:** bool  ·  **Default:** `False` If ``True``, then water that a) reaches the edge of the grid and b) is at a local minimum in terms of the cell's water level will disappear from the model, i.e. it moves outside of the model domain. This may or may not be a good assumption depending on location. ### `flow_speed_scaling` **Type:** float  ·  **Default:** `1.0` Determines how much water can flow from a cell in the firn to its neighbours during the lateral flow step. The amount of water that can flow is determined by the density of the cell, and the available water in the cell. This flag scales the amount of water that *can* flow by the value given - it will not move more water than there is in the cell. It has no effect on the amount of water that can flow from lakes - since it is assumed that all water is available to move from lakes. ### `outflow_proportion` **Type:** float  ·  **Default:** `1.0`  ·  **Allowed:** between 0.0 and 1.0 Determines how much water will flow out of the catchment as a proportion of the total water available to flow out. If ``1``, then all water that is at a local minimum and adjacent to the edge of the grid will flow out. Setting it to ``0`` will effectively set ``catchment_outflow`` to ``False``. ## IO ### `output_grid_size` **Type:** int  ·  **Default:** vertical_points_firn Size of the vertical grid that you want to write to. This can be different from the size of the grid used in the actual model calculations, in which case the results are interpolated to this grid size. Useful to reduce the size of output files, which can be large. ### `output_timestep` **Type:** int  ·  **Default:** `1` Write model output every ``output_timestep`` model days. Useful if you want to save data less regularly than every timestep, e.g. if filesizes are getting too large and you don't need daily resolution. ### `vars_to_save` **Type:** tuple  ·  **Default:** `('firn_temperature', 'Sfrac', 'Lfrac', 'firn_depth', 'lake_depth', 'lid_depth', 'lake', 'lid', 'v_lid', 'ice_lens_depth')` Tuple containing the names of the variables that we wish to save during the evolution of MONARCHS over time. If you want to save a particular diagnostic, then you should add it here. See the variable catalogue in ``monarchs.variables`` for the full list of variables that ``vars_to_save`` accepts. ### `save_output` **Type:** bool  ·  **Default:** `False` Flag to determine whether you want to save the output of MONARCHS to netCDF. If True, save the variables defined in ``vars_to_save`` into a netCDF file at ``output_filepath`` every timestep, i.e. save spatial and temporal data for the selected variables. File sizes can get rather large for large model grids and long runs. Note that this is separate from dumping, where only a snapshot of the current iteration is saved - it is not possible to restart MONARCHS from the output defined here. ### `output_filepath` **Type:** str  ·  **Default:** optional (unset) Path to the file that you want to save output into, including file extension. Required if ``save_output`` is ``True``. MONARCHS uses netCDF for saving output data, so this may be e.g. ``/work/monarchs/monarchs_run1.nc``. ### `dump_data` **Type:** bool  ·  **Default:** `False` Flag that determines whether to dump the current model state at the end of each iteration (day). Doing so will allow the user to restart MONARCHS in the event of a crash. If this is ``True``, then you also need to specify ``dump_filepath``. Note that dumping the model state is separate to setting model output - this only dumps a snapshot of the model in its current state, needed to restart the model. ### `dump_filepath` **Type:** str  ·  **Default:** optional (unset) File path to dump the current model state into at the end of each timestep. Required if ``dump_data`` or ``reload_from_dump`` are True. ### `dump_timestep` **Type:** int  ·  **Default:** `1` How often to write model checkpoint states. Default is every timestep. Set to a value greater than 1 to write checkpoints less frequently. ### `dump_checkpoint_frequency` **Type:** int  ·  **Default:** `0` Write an extra numbered checkpoint every N days. 0 = off. Used for debugging mainly. ### `dump_data_pre_lateral_movement` **Type:** bool  ·  **Default:** `False` ### `reload_from_dump` **Type:** bool  ·  **Default:** `False` Flag to determine whether we want to reload from a dump (see ``dump_data`` for details). If ``True``, reload model state from file at the path determined by ``dump_filepath``. ## Runtime ### `use_numba` **Type:** bool  ·  **Default:** `True` Toggle whether to jit-compile the code using Numba or not. Gives a performance boost, but may not always work and adds a few complications. See the Numba page of the documentation for more details. ### `parallel` **Type:** bool  ·  **Default:** `True` Determines whether or not to run in parallel, or serially. If running in parallel, then performance is improved since the model will run many of the single-column gridpoints at the same time. Parallelism comes via Numba's ``prange`` function, which works similarly to an OpenMP ``parallel do`` loop, so this requires ``use_numba``. ### `use_mpi` **Type:** bool  ·  **Default:** `False` MPI support is not yet implemented. ### `cores` **Type:** str or int  ·  **Default:** `'all'` Number of processing cores to use. 'all' or ``False`` will instruct MONARCHS to use all available CPU cores, else it will use however many you specify. You may want to manually specify this to something lower than the number of cores on your system if e.g. running on a laptop which you are using for other purposes, or if running on HPC and you are experiencing memory bottleneck issues. ### `ignore_errors` **Type:** bool  ·  **Default:** `False` If ``True``, then ``monarchs.core.utils.check_correct`` will never be invoked, i.e. the model may be free to evolve into an unphysical state. Errors may still occur, but these will be Python errors rather than MONARCHS errors if so. May be useful for debugging.