This documentation provides instructions for how to contribute your own documentation pages to this site, including an example reStructuredText file which can be used as a template.

This page describes the process of contributing to this documentation. This is
a good place to place documentation on software or projects within the
BCPU. There is a simple six-step workflow described in this first section,
and there are more detailed notes on each step to guide you through the process.

Get the up-to-date code.

| 1.1. If this is your first time contributing to the documentation, clone the GitHub repository.
| 1.2. If not, then pull the most up-to-date documentation.

1.1. If this is your first time contributing to the documentation, clone the GitHub repository.

Make changes to the documentation files in the source directory, either:

| 2.1. Modify an existing page.
| 2.2. Add a new page to an existing category.
| 2.3. Add a new category.

This will need to clone the repository `BCPU-documentation <https://github.com/BjerknesCPU/BCPU-documentation>`_.

You should clone the GitHub repository to NIRD so that you have all the tools
available for this workflow. First navigate to /projects/NS9039K/www/<user>
where <user> is a user directory owned by you. If you do not have a directory
in /projects/NS9039K/www/ then create one with your name, username or initials.

Once you are in this directory, clone the repository with the command
``git clone git@github.com:BjerknesCPU/BCPU-documentation.git``
which will produce a directory 'BCPU-documentation/' in your current working
directory. Change directory into this directory.

which will produce a directory ‘BCPU-documentation/’ in your current working

For more on cloning, see this
`page <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository>`_.
If you have never used the organisational GitHub before, you may have to
`set up ssh keys <https://docs.github.com/en/enterprise-server@3.0/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_.
If you have issues with this step, or with access to the GitHub repository,
please contact our :doc:`internal support <../support/support>`.

.

`set up ssh keys <https://docs.github.com/en/enterprise-server@3.0/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_

.
please contact our 

In your local directory of the Git repository (by standard named BCPU-documentation) switch to the main branch. ::

In your local directory of the Git repository (by standard named BCPU-documentation) switch to the main branch.

Within the BCPU-documentation/ directory, all changes are made to the 'source'
which exists within the source/ directory. In this documentation, the source
files are written in reStructuredText, which is a type of markup. Writing in
this format allows the build files to be automatically generated from the
source files.

Within the BCPU-documentation/ directory, all changes are made to the ‘source’

Here is an introduction to
`reStructuredText <https://docutils.sourceforge.io/docs/user/rst/quickstart.html>`_
but an easy way of getting started is to copy the format of existing
documentation in the source directory.

Each page on the
documentation `site <https://bjerknescpu.github.io/BCPU-documentation/>`_
corresponds to one .rst file in the source directory. These .rst files are
organised into 'categories', for example 'storage' or 'support'.

organised into ‘categories’, for example ‘storage’ or ‘support’.

If you wish to modify an existing documentation page, you need to locate the
.rst file for the page in the source directory, and then make make modifications
to the text in the file.

If you wish to add a new documentation page, follow the following steps,
we will use the template file: source/contribute/example.rst.

Copy and rename the example template into your desired destination category,
for example if you want to make a new documentation page about the
seasonal forecast: ``cp source/contribute/example.rst source/seasonal_forecast/new_page.rst``

seasonal forecast: 

``cp source/contribute/example.rst source/seasonal_forecast/new_page.rst``

cp source/contribute/example.rst source/seasonal_forecast/new_page.rst

Once you are happy with the file, you need to add a link to the file in the category index.
This should be a .rst file with the same name as the category.

If you want to create a new category for documentation, then follow these steps:

Create a new directory in source/ ``cd source``  to hold pages on the new category ``mkdir new_category``.

Copy the index page template for the new category ``cp contribute/example_index.rst new_category/new_category.rst``.

``cp contribute/example_index.rst new_category/new_category.rst``

Add new documentation page links to the toctree directive (as in previous example).

Add the new category to the first section of the master index tree source/index.rst.

The documentation is built using
`Sphinx <https://www.sphinx-doc.org/en/master/>`_. In order to use Sphinx, you
will need to load an environment which contains the library. On NIRD, this is
our shared conda environment, which can be activated as follows:

. In order to use Sphinx, you

The documentation is built by calling: ``make github`` in the
BCPU-documentation/ directory.

This will use the files in the source/ directory to generate html files in the
build/ directory. These are then automatically copied to the docs/ directory,
which is where the documentation is read from for the website. These
changes are not applied to our documentation website until we push back to
GitHub. Have a look at your changes before you make them visible to
everyone else (see next step).

Once you have run the ``make github`` command, the built files should be
available in the docs/ directory. It is good practice to view these
files before pushing them to GitHub. Because you have been working in the
project www/ directory, you can check these files
`here <http://ns9039k.web.sigma2.no>`_. In the web interface, navigate into
your user directory, and open the file 'index.rst', which is the index page
of the documentation. From here you should be able to check what the
documentation looks like before you push it to our shared website.

 command, the built files should be

. In the web interface, navigate into
your user directory, and open the file ‘index.rst’, which is the index page

Run the command ``git pull`` to make sure you have the most up to date
version of the documentation.

 to make sure you have the most up to date

Run the command ``git add -A`` which will stage all your changes.

Run the command ``git commit -m "<MESSAGE>"`` but replace <MESSAGE> with
a brief description of your changes, for example "Added Support documentation
page".

 but replace <MESSAGE> with
a brief description of your changes, for example “Added Support documentation
page”.

Run the command ``git push`` which will push your changes to the remote
repository, which will automatically update the GitHub documentation page.

 which will push your changes to the remote

Once you have done pushed the changes to the GitHub, the
`online pages <https://bjerknescpu.github.io/BCPU-documentation/>`_ should
automatically update after 1-2 minutes (this is not immediate).

`online pages <https://bjerknescpu.github.io/BCPU-documentation/>`_

 should

A short description of the category, will appear on the index page for the category.
Replace <page1.rst> and <page2.rst> with the names of pages in the category directory.

This page contains some brief notes about the seasonal forecast which is run every month for the Climate Futures project. The seasonal forecast consists of 60 ensemble members and is run every month. Some basic anomaly, quantile and index plots are made available `here <http://ns9039k.web.sigma2.no/seasonal_forecast/>`_.

This page contains some brief notes about the seasonal forecast which is run every month for the Climate Futures project. The seasonal forecast consists of 60 ensemble members and is run every month. Some basic anomaly, quantile and index plots are made available 

Raw hindcasts for the seasonal forecast are located in NIRD in /projects/NS9873K/norcpm-cf/raw/norcpm-cf-system1/norcpm-cf-system1_hindcast1/. Hindcasts and forecasts are also regridded, and their metadata modified in order to match other C3S seasonal forecasts for provision to the Climate Futures project. Select post-processed variables are available through the NS9039K web interface at http://ns9039k.web.sigma2.no/seasonal_forecast/climate_futures/.

Raw hindcasts for the seasonal forecast are located in NIRD in /projects/NS9873K/norcpm-cf/raw/norcpm-cf-system1/norcpm-cf-system1_hindcast1/. Hindcasts and forecasts are also regridded, and their metadata modified in order to match other C3S seasonal forecasts for provision to the Climate Futures project. Select post-processed variables are available through the NS9039K web interface at 

In order to perform accurate forecasts each month, up-to-date SST, salinity and temperature data is assimilated into the system. The SST data assimilated is the OISSTv2 data from NOAA, which from December 2022 is being replaced by the OISSTv2.1 dataset. Temperature and salinity profiles are downloaded from the UK Met Office EN4.2.2. dataset `here <https://www.metoffice.gov.uk/hadobs/en4/download-en4-2-2.html>`_.

In order to perform accurate forecasts each month, up-to-date SST, salinity and temperature data is assimilated into the system. The SST data assimilated is the OISSTv2 data from NOAA, which from December 2022 is being replaced by the OISSTv2.1 dataset. Temperature and salinity profiles are downloaded from the UK Met Office EN4.2.2. dataset 

This page provides documentation on how to process the seasonal forecast every month. This begins with running scripts that modify metadata so that the forecast can be provided in a C3S-like format to the Climate Futures project. After this, some standard plots and indices are produced, and `the website <http://ns9039k.web.sigma2.no/seasonal_forecast/index.html>`_. is updated.

This page provides documentation on how to process the seasonal forecast every month. This begins with running scripts that modify metadata so that the forecast can be provided in a C3S-like format to the Climate Futures project. After this, some standard plots and indices are produced, and 

`the website <http://ns9039k.web.sigma2.no/seasonal_forecast/index.html>`_

In order to perform the metadata processing, you will need to load the shared conda environment on NIRD. ::

In order to perform the metadata processing, you will need to load the shared conda environment on NIRD.

Then you need a copy of the GitHub repository with the processing scripts. If you don't already have this, then take a clone of it. ::

Then you need a copy of the GitHub repository with the processing scripts. If you don’t already have this, then take a clone of it.

Now run h0.atm and h2.atm to process monthly and six-hourly data respectively.
You need to modify the INPUT_GLOB and OUTPUT_DIR variables in the Input section of both files, then run. ::

You need to modify the INPUT_GLOB and OUTPUT_DIR variables in the Input section of both files, then run.

These should produce files in your selected output directory which have modified metadata.
These should be placed somewhere that can be accessed by Alex Lenkoski, the current location is: ::

These should be placed somewhere that can be accessed by Alex Lenkoski, the current location is:

Please follow the existing directory structure to make Alex's processing easier.
Email Alex (lenkoski@nr.no) and Ole (owul@norceresearch.no) to let them know that the forecast is complete.

Please follow the existing directory structure to make Alex’s processing easier.
Email Alex (

Now the delivery to the Climate Futures team is complete, we will generate some plots and place them on the NS9039K website.

In order to produce ENSO and IOD index plots, we need up-to-date ERA5 data, so update this first: ::

In order to produce ENSO and IOD index plots, we need up-to-date ERA5 data, so update this first:

cd /projects/NS9039K/data/external/reanalysis/ECMWF/ERA5/scripts
python download_era5_recent.py

This should download ERA5 data for 202101-Present and run a conversion to NetCDF using CDO.
Check this downloaded correctly and converted to NetCDF: ::

Check this downloaded correctly and converted to NetCDF:

Then modify the two index plot scripts. You need to modify two input arguments at the top (marked clearly within the scripts).
The scripts should output the ENSO and IOD plots to the correct location. ::

The scripts should output the ENSO and IOD plots to the correct location.

cd C3S-NorCPM-CF
vi enso_plot.py
python enso_plot.py
vi iod_plot.py
python iod_plot.py

Run the mean anomaly and quantile plotting scripts. Make sure to update the input and output locations and dates. Run twice, once for 'global' and once for 'europe': ::

Run the mean anomaly and quantile plotting scripts. Make sure to update the input and output locations and dates. Run twice, once for ‘global’ and once for ‘europe’:

Quantile and mean anomaly plots are generated by comparing the forecast to pre-calculated mean and quantile values, these values exist in files in: ::

Quantile and mean anomaly plots are generated by comparing the forecast to pre-calculated mean and quantile values, these values exist in files in:

In the normal seasonal forecast production, these do not have to be modified, but if there are changes to the data request (e.g. modification of the grid or addition of variables) then these will have to be regenerated using the scripts in the C3S-NorCPM-CF repository: ::

In the normal seasonal forecast production, these do not have to be modified, but if there are changes to the data request (e.g. modification of the grid or addition of variables) then these will have to be regenerated using the scripts in the C3S-NorCPM-CF repository:

You need to update the index file to display the new plots on the website. ::

You need to update the index file to display the new plots on the website.

Add the current date as the top option in the issueSelectQuantile form

<form>
<b> Issue Date </b>
<select id="issueSelectQuantile" onchange="updateIssueQuantile()" autocomplete="off">
<option selected> 2022-10 </option> <!-- Replace with most recent date -->
<option> 2022-09 </option> <!-- Add extra line for second most recent date -->
<option> 2022-08 </option>
<option> 2022-07 </option>
<option> 2022-06 </option>
<option> 2022-05 </option>
</select>
</form>

Add the current date as the top option in the issueSelectAnomaly form

<form>
<select id="issueSelectAnomaly" onchange="updateIssueAnomaly()" autocomplete="off">
<option selected> 2022-10 </option> !-- Replace with most recent date -->
<option> 2022-09 </option> !-- Add extra line for second most recent date -->
</select>
</form>

Now the forecast production and processing is complete! Have a look at the forecasts `here <http://ns9039k.web.sigma2.no/seasonal_forecast/index.html>`_.

Now the forecast production and processing is complete! Have a look at the forecasts 

This page provides documentation on how to run the NorCPM seasonal forecast. In general there are four steps to this process:

Run forward the analysis to present day, using new observational data.

The forecast should always be provided on the evening of the 14th of the month, as our collaborators need it on the 15th.

The Met Office provides monthly updates to EN4.2.2. observational temperature and salinity profiles, and these updates happen on the 9th-17th of each month. If this update can be included into the assimilation then this is good, as it gives us an additional month of temperature and salinity data to assimilate. You can check when the last update was on the Met Office `site <https://www.metoffice.gov.uk/hadobs/en4/download-en4-2-2.html>`_ (see bottom of page, or look at file links). I would recommend running the analysis on the 12th/13th of the month. It takes ~3 hours to run. I would then recommend running the prediction on the 12/13th, this takes ~2 hours. The post processing takes another ~2 hours. Therefore, if there are no issues the whole workflow takes around 1 working day, but doing this on the 12/13th allows for potential issues (e.g. machine instability) to be addressed. It is important to keep an eye out for Betzy downtime announcements in the week preceding the 15th to ensure there is no significant disruption.

The Met Office provides monthly updates to EN4.2.2. observational temperature and salinity profiles, and these updates happen on the 9th-17th of each month. If this update can be included into the assimilation then this is good, as it gives us an additional month of temperature and salinity data to assimilate. You can check when the last update was on the Met Office 

 (see bottom of page, or look at file links). I would recommend running the analysis on the 12th/13th of the month. It takes ~3 hours to run. I would then recommend running the prediction on the 12/13th, this takes ~2 hours. The post processing takes another ~2 hours. Therefore, if there are no issues the whole workflow takes around 1 working day, but doing this on the 12/13th allows for potential issues (e.g. machine instability) to be addressed. It is important to keep an eye out for Betzy downtime announcements in the week preceding the 15th to ensure there is no significant disruption.

The first step in running the seasonal forecast is to update the observational data that is assimilated into the analysis.

cd /cluster/shared/noresm/norcpm/Obs/TEM/EN422/
./Update_profile.sh

When it comes to running the analysis, it is important to note that some of the temperature and salinity profiles are initially uploaded by the Met Office as 'preliminary', and then are replaced later by 'final' files. We always want to run the analysis with the best possible data, which means that each month, we will re-run the part of the analysis that used 'preliminary' data last month. This means that it is important to keep track of what the latest observational files are each month.

When it comes to running the analysis, it is important to note that some of the temperature and salinity profiles are initially uploaded by the Met Office as ‘preliminary’, and then are replaced later by ‘final’ files. We always want to run the analysis with the best possible data, which means that each month, we will re-run the part of the analysis that used ‘preliminary’ data last month. This means that it is important to keep track of what the latest observational files are each month.

A log file of each SST, temperature and salinity retrieval has automatically be generated by the download scripts. This includes a file listing, so that the most recently downloaded final and preliminary files can be seen.

This means that we have preliminary profiles for 2022/08 and final profiles for 2022/07. Next month when we run the analysis, we will run it from 2022/07.

Move into the analysis directory. The settings file for this seasonal forecast is then in settings/default_settings_VCF.sh ::

Move into the analysis directory. The settings file for this seasonal forecast is then in settings/default_settings_VCF.sh

cd /cluster/projects/nn9039k/people/tbi045/NorCPM/analysis/
ls settings/default_settings_VCF.sh

Check which date should be the start date for the analysis run this month. This is the date of which the last 'final' EN.4.2.2. file was for last month's run.

Check which date should be the start date for the analysis run this month. This is the date of which the last ‘final’ EN.4.2.2. file was for last month’s run.

Check if the correct restart files for your start date exist in your run directory (usually these will be automatically deleted). ::

Check if the correct restart files for your start date exist in your run directory (usually these will be automatically deleted).

If they do not exist, then you need to copy them over by providing the start date as an argument in the form YYYY-MM-DD. ::

If they do not exist, then you need to copy them over by providing the start date as an argument in the form YYYY-MM-DD.

To run the analysis, make sure that you load the correct environments, and make sure you provide a start date argument to sbatch in the form YYYY-MM-DD ::

To run the analysis, make sure that you load the correct environments, and make sure you provide a start date argument to sbatch in the form YYYY-MM-DD

source /cluster/projects/nn9039k/people/tbi045/NorCPM/analysis/load_envs.sh
sbatch submit_reanalysis_VCF.sh YYYY-MM-DD

Check that the analysis ran to the expected month (it will crash when there is no more data to assimilate for a month).

Create a new use_case file. The date in the filename should be changed to the date of last data assimilated. The date inside the file needs to be changed in two places ::

Create a new use_case file. The date in the filename should be changed to the date of last data assimilated. The date inside the file needs to be changed in two places

cp norcpm-cf-system1_hindcast1_20221015.in norcpm-cf-system1_hindcast1_<date>.in
vi norcpm-cf-system1_hindcast1_<date>.in

Create a template, create an ensemble, and submit the prediction. ::

Create a template, create an ensemble, and submit the prediction.

Check that the prediction ran to the expected month, and was archived correctly e.g. check files have been moved to archive. ::

Check that the prediction ran to the expected month, and was archived correctly e.g. check files have been moved to archive.

cd /cluster/projects/nn9039k/people/tbi045/NorCPM/tools
vi mergediag.sh
sbatch mergediag.sh

This produces a merged directory in the archive (takes some time) e.g. ::

This produces a merged directory in the archive (takes some time) e.g.

Copy forecast files to NIRD, using scp or rsync from above directory. e.g. ::

Copy forecast files to NIRD, using scp or rsync from above directory. e.g.

Delete restart files that will not be needed anymore. You need to determine which restart files you will need next month.
The analysis next month should start from the last 'final' assimilation files that were used, so in this example, if temperature and salinity profiles were noted down as: ::

The analysis next month should start from the last ‘final’ assimilation files that were used, so in this example, if temperature and salinity profiles were noted down as:

Then the analysis will continue from 202207, so keep these restart files, with care, remove any others e.g. ::

Then the analysis will continue from 202207, so keep these restart files, with care, remove any others e.g.

cd /cluster/work/users/${USER}/archive/norcpm-cf-system1_assim_19811115/
rm -rf norcpm-cf-system1_assim_19811115_mem??/rest/2022-04-15-00000/

sbatch fanf_noresm2netcdf4.pbs

Check the files on NIRD, and this concludes generation of the forecast. For steps on processing the output, please see the separate documentation page.

This documentation is designed to allow the user to run and post-process the seasonal NorCPM1 forecast, which produces output for the Climate Futures project.

This page provides documentation on how members of the BCPU can get technical
support from others within the team.

In order to keep technical requests in a central and discoverable place, we
are using GitHub Issues as an issue tracker. Requests for support can be made
on the 'Issues' tab of the GitHub repository BjerknesCPU/BCPU-support.

on the ‘Issues’ tab of the GitHub repository BjerknesCPU/BCPU-support.

In order to access this repository to use the issue tracker, you will need a
GitHub account and you will need to be added to the BjerknesCPU GitHub
organization. To be added to this, please contact BCPU-support@uib.no.

organization. To be added to this, please contact 

Within the BCPU-support repository on GitHub, navigate to the 'Issues' tab
where you should be able to see existing requests. To create your own request
here, select 'New issue', and a 'Template request' should appear. Click
'Get Started' and fill in the fields of the template to make the request.

Within the BCPU-support repository on GitHub, navigate to the ‘Issues’ tab
here, select ‘New issue’, and a ‘Template request’ should appear. Click
‘Get Started’ and fill in the fields of the template to make the request.

Support for the request will then be followed up as replies on the issue,
and the issue will be closed once it is resolved.

As an alternative to the GitHub Issue system, there is also a mailing list
(BCPU-support@uib.no) to which technical requests can be directed.
These requests will get picked up by someone in the team, who will respond to
the request via email and also copy the request to the issue tracker.

(

) to which technical requests can be directed.

Extension internationalization (i18n) and localization (l10n) using i18n API

sphinx.ext.imgconverter – A reference image converter using Imagemagick

sphinx.ext.autosectionlabel – Allow reference sections using its title

sphinx.ext.napoleon – Support for NumPy and Google style docstrings

f-strings support = for self-documenting expressions and debugging

ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON 3.12.1 DOCUMENTATION

email.message.Message: Representing an email message using the compat32 API

What is the most efficient way to concatenate many strings together?

Why does a_tuple[i] += [‘item’] raise an exception when the addition works?

What does the slash(/) in the parameter list of a function mean?

Why am I getting an UnboundLocalError when the variable has a value?

PEP 3118: New memoryview implementation and buffer protocol documentation

PEP 476: Enabling certificate verification by default for stdlib http clients

PEP 471 - os.scandir() function – a better and faster directory iterator

PEP 655: Marking individual TypedDict items as required or not-required

Why must ‘self’ be used explicitly in method definitions and calls?

argparse — Parser for command-line options, arguments and sub-commands

functools — Higher-order functions and operations on callable objects

importlib.resources – Package resource reading, opening and access

multiprocessing.shared_memory — Shared memory for direct access across processes

sysconfig — Provide access to Python’s configuration information