Build and deployment documentation #280
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,44 @@ | ||||||
| # Build infrastructure | ||||||
|
|
||||||
| Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page. | ||||||
|
|
||||||
|
Collaborator
There was a problem hiding this comment. Do we need to define release and deploy, we use them both, slightly interchangeably |
||||||
| ACCESS-NRI is using [Spack](https://spack.io/), a build from source package manager designed for use with high performance computing. | ||||||
|
|
||||||
| ## Software structure | ||||||
|
|
||||||
| ACCESS-ESM1.6 being a Earth System model, it is constituted of several model components, each residing in its own repository on GitHub. In addition, some model components need other utilities at compilation time that are stored in separate repositories. This results in a complex software structure involving a large number of repositories: | ||||||
|
Collaborator
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| - deployment repository: | ||||||
| - [ACCESS-NRI/ACCESS-ESM1.6](https://github.com/ACCESS-NRI/ACCESS-ESM1.6) | ||||||
| - model components: | ||||||
| - [ACCESS-NRI/cice5](https://github.com/ACCESS-NRI/cice5) | ||||||
| - [ACCESS-NRI/GFDL-generic-tracers](https://github.com/ACCESS-NRI/GFDL-generic-tracers) | ||||||
| - [ACCESS-NRI/MOM5](https://github.com/ACCESS-NRI/MOM5) | ||||||
| - [ACCESS-NRI/UM7](https://github.com/ACCESS-NRI/UM7) | ||||||
| - [CABLE-LSM/CABLE](https://github.com/CABLE-LSM/CABLE) | ||||||
| - other software: | ||||||
| - [ACCESS-NRI/FMS](https://github.com/ACCESS-NRI/FMS) | ||||||
| - [ACCESS-NRI/mocsy](https://github.com/ACCESS-NRI/mocsy) | ||||||
| - [ACCESS-NRI/GCOM4](https://github.com/ACCESS-NRI/GCOM4) | ||||||
|
|
||||||
| !!! note | ||||||
|
|
||||||
| The _UM7_ and _GCOM4_ repositories are private because these software are not open-source. They are covered by the UKMO's Momentum Partnership licence. To gain access to these repositories, please request an invitation via [this ACCESS-Hive forum topic](https://forum.access-hive.org.au/t/request-access-to-access-esm1-6-component-repositories/5709). | ||||||
|
|
||||||
| ## Building ACCESS-ESM1.6 using the deployment infrastructure | ||||||
aidanheerdegen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| This is the recommended method to build ad-hoc versions of ACCESS-ESM1.6 because it does not require users to have access to all the repositories, it handles the build automatically and it provides traceability and shareability of the deployment. | ||||||
|
Collaborator
There was a problem hiding this comment. It needs an introduction sentence e.g. It is possible to:
|
||||||
|
|
||||||
| This method is explained on the ACCESS-Hive page for [creating pre-releases and releases](https://docs.access-hive.org.au/models/build_a_model/create_a_prerelease/) of ACCESS models. For ACCESS-ESM1.6, you will need _write permissions_ on the [ESM1.6 deployment repository](https://github.com/ACCESS-NRI/ACCESS-ESM1.6) and on any model component you need to modify. Request these permissions via this [ACCESS-Hive forum topic](https://forum.access-hive.org.au/t/request-access-to-access-esm1-6-component-repositories/5709). | ||||||
|
|
||||||
| !!! warning | ||||||
|
|
||||||
| This method to build the model only works if your modifications are committed in branches of the model repositories on GitHub listed in the [software structure](#software-structure). This method can not be used if your modifications sit in a fork of one of the repositories or a local clone. | ||||||
|
|
||||||
| ## Local build of ACCESS-ESM1.6 | ||||||
|
|
||||||
| The Spack infrastructure allows you to create your own local build on _Gadi_ for ACCESS-ESM1.6. Once setup, this might be faster than using the deployment infrastructure, especially when you want a lot of small incremental builds during development. | ||||||
|
Collaborator
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| However, this method has several drawbacks. It requires users to install the Spack software which can make it harder for ACCESS-NRI to provide support. It requires users to have at least _read permissions_ on all the repositories required by ACCESS-ESM1.6 (see [Software structure](#software-structure)). It builds the model in the user space on _Gadi_ thus potentially exposing licensed source code to unlicensed users, limiting the shareability of the build and consuming a potentially non-insignificant amount of inodes. Finally, contrary to the deployment infrastructure, it does not provide an easy way to access several test builds from the same model component branch at the same time. | ||||||
|
Collaborator
There was a problem hiding this comment. I think the main issue that there is some level of effort to set up and understand it.
Collaborator
There was a problem hiding this comment.
Suggested change
Collaborator
There was a problem hiding this comment. I don't think number of inodes are a real problem for an individual developer. Also if folks have access to the UM source code then they have the appropriate permissions to see the source code. |
||||||
|
|
||||||
| This method is explained on the ACCESS-Hive page for [modifying an ACCESS model's source code](https://docs.access-hive.org.au/models/build_a_model/build_source_code/). | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Deployment | ||
|
|
||
| All released versions of ACCESS-ESM1.6 come with a pre-deployed build on _Gadi_. Deployed builds are stored under the project `vk83` (hence requiring [membership to this project](https://my.nci.org.au/mancini/project/vk83/join) for access). You can see all deployed builds via: | ||
|
Collaborator
There was a problem hiding this comment. Mostly the words a "release version" would refer to a configuration, not a model exe I think the point here is - release configurations use a certain deployment of the model code. Mostly users wouldn't mess with that. Up to date configs will use the latest deployment, the older ones are kept for folks who are running experiments based on older configurations
Collaborator
There was a problem hiding this comment. this project membership is surely self evident by this point, its where payu is available from |
||
|
|
||
| ```bash | ||
| module use /g/data/vk83/modules | ||
| module avail access-esm1p6 | ||
| ``` | ||
|
|
||
| There are development releases (identified with a `dev_` prefix to the date tag) and full releases (identified with only a date tag). We recommend new users start with the newest full release (i.e., with the most recent date tag). | ||
|
Collaborator
There was a problem hiding this comment. This isn't really a page for new users. What we actually recommend is that new users use a released configuration |
||
|
|
||
| These builds are optimised for the Sapphire-Rapid hardware from Intel (i.e., the *normalsr* queue), and may not run on Cascade-Lake (i.e., the *normal* queue) or older hardware. | ||
|
Collaborator
There was a problem hiding this comment. I'm pretty confident it would run fine on normal. I can't see any HW specific optimisation going on |
||
|
|
||
| The ACCESS-ESM1.6 model configurations released by ACCESS-NRI are setup to use the proper model release and will be updated when necessary. | ||
|
|
||
|
|
||
| ## Release information | ||
|
|
||
| The deployment process creates a GitHub release with the same tag as the deployed module. All releases are available under the [Releases page](https://github.com/ACCESS-NRI/ACCESS-ESM1.6/releases). Each release has a changelog and meta-data with detailed information about the build and deployment, including: | ||
|
|
||
| - paths on Gadi to all executables built in the deployment process (spack.location) | ||
| - a spack.lock file, which is a complete build provenance document, listing all the components that were built and their dependencies, versions, compiler version, build flags and build architecture | ||
| - the environment spack.yaml file used for deployment | ||
|
|
||
| ## Deployment process | ||
|
|
||
| The deployment is managed via GitHub Actions that are triggered when a new version of the spack.yaml file is committed to the `main` branch or a dedicated `backport/VERSION` branch of the [ACCESS-NRI/ACCESS-ESM1.6](https://github.com/ACCESS-NRI/ACCESS-ESM1.6) repository. | ||
|
|
||
| No manual deployments will be accepted. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The link to Deployment page doesn't work , this might be correct