Making changes to MONARCHS ==================================== Some of the below is only relevant if you want your change to be merged into the main branch of MONARCHS, or you want your changes to benefit from the performance gains obtained by using Numba. Adding new diagnostics or physics ********************************** If adding new variables to the code, you will need to do the following: - Add the variable into the ``IceShelf`` class, found in ``monarchs.core.iceshelf_class``, and initialising it if appropriate in ``monarchs.core.initial_conditions.create_model_grid``. - Add the variable into the model code itself. This likely involves making the relevant changes to the various files/functions in ``monarchs.physics``. - If your new variable is a diagnostic, add the variable to ``vars_to_save`` in your runscript, so that the code knows to track it over time and save it to the output netCDF file. - If your new variable relies on a toggle or other ``model_setup`` variable, set a default value for this in ``monarchs.core.configuration.create_defaults_for_missing_flags``. If using Numba (see :doc:`advanced` and the section below), you will also need to: - Add the variable into ``spec``, found in ``monarchs.core.iceshelf_class.get_spec()``, including its ``dtype``. Compare with other variables in ``spec`` for the syntax. This step is essential for the code to work with Numba support. Merging your changes into the MONARCHS source ********************************************* If you have added anything to the MONARCHS source code, please let us know! We welcome pull requests from users who have added features or squashed bugs that we have let slip through the net. Please make any changes you want to make to the code in a new branch of the main repo (i.e. not ``main``), or create a fork. Pushes directly into ``main`` are not allowed even if you are a collaborator in the ``monarchs-ice`` organisation. For your work to be merged into ``main``, it needs to pass our test suite. The tests are automatically run via Github Actions when a pull request into ``main`` is made, so it will quickly be apparent if it does not pass. The main one to look out for is the tests in ``tests/numba`` - if any new ``IceShelf`` variables are not added into ``spec`` this test will fail. Additionally, any new functions or physics/diagnostics should have docstrings or comments where possible. If you have written new physics functions, it is best if these have some kind of unit test. Any new physics should have an associated toggle defined in ``model_setup.py``, added to ``toggle_dict`` in ``monarchs.core.driver.setup_toggle_dict``, and a switch to turn it on or off using the value of ``toggle_dict``. Any changes that require amendments to ``model_setup.py`` should have suitable documentation added to ``docs/source/model_setup_reference.rst``. Advanced users ------------------------------------ Adding functions with Numba support *********************************** (first, see :doc:``advanced`` for some background information). *If* Numba support is useful for your change, consult `the Numba documentation `_ to ensure that your code uses only pure Python and ``numpy`` functions. Using other modules (e.g. ``scipy``) is not supported by Numba, and therefore the code won't work with the ``use_numba`` optimisation flag set in ``model_setup.py``. This will mean that the model as a whole runs slower. If your function is included within any of the existing ``physics`` modules (with the exception of ``heateqn`` and ``solver``), or within ``utils`` or ``timestep`` in ``core``, then provided that it fits the Numba specifications, Numba support should be automatic, i.e. MONARCHS will automatically try and jit the function. If you add a function that you specifically do not want to apply Numba decoration to (e.g. the code is not called by other Numba code and contains incompatible code), you can ensure that this step is avoided using the ``do_not_jit`` decorator in ``core.utils``.