Create how to build a model page

[atteggiani]

Fixes #743

Draft of the page for feedback on the use of the tabs above.

[github-actions]

PR Preview
🚀 Deployed preview to https://access-hive.org.au/pr-preview/pr-777
2024-09-30 03:26 AEST

[atteggiani]

Following up a chat with @harshula, he will provide a draft content for the page that will then be reviewed and formatted to match Hive Docs guidelines.

[harshula]

2024/09/19: Moved to the new PR: #789 (comment)

[atteggiani]

Hi @atteggiani , Is this suitable for the first step?

Hi @harshula,
Thank you for working on this.

What you wrote looks pretty good.

I have a few comments on what you wrote and more in general on what I think the new content on model builds should include in the Hive Docs:

• I think the key information that the end-user wants/needs is "how to build an ACCESS-NRI released model", so we definitely need instructions on that. Probably the best fit is a stand-alone page on how to build a model, with tabs to choose a specific model.
• ACCESS-NRI released model are built through spack, so it is important for the model build step that the users have a "spack environent" ready to use. The content you wrote above fits very well as an introductory step on how to set up this "spack environment" on Gadi. It could be placed in the "Getting started" section of the Hive Docs and linked in the "how to build an ACCESS-NRI released model" page (in the point above) as a pre-requisite.
• As much as the point above applies and we could go forward with it, I think all the steps you listed in the spack set-up instructions could be done in advance as a versioned environment on Gadi, to be loaded as a module through module load (e.g. module load access-spack).
  I think this would:
  • simplify a lot the experience for the user
  • ensure the user has the proper "spack environment" with the right versions of spack, spack-packages and spack-configs, depending on the module they load (for example module load access-spack/0.22 rather than module load access-spack/0.20)

Has anything like this been discussed in the release team?
What are your thoughts?

[harshula]

Hi @atteggiani , The Spack instances in vk83 on Gadi are read-only. The set-up instructions above are for those that need a writable Spack instance in-order to build the models.

[atteggiani]

Hi @atteggiani , The Spack instances in vk83 on Gadi are read-only. The set-up instructions above are for those that need a writable Spack instance in-order to build the models.

Ok, sorry the misunderstanding might come from my very poor knowledge of how spack works.

spack-packages and spack-config are what is actually used by spack for the build right?
In spack-packages one should include, for example, the source code of a component?

In that case it makes sense, but isn't the first repo the spack executable itself? (git clone -c feature.manyFiles=true https://github.com/ACCESS-NRI/spack.git --branch releases/v0.22 --single-branch --depth=1)
Why can't users simply use the spack executable in vk83?

[harshula]

Hi @atteggiani , The Spack instances in vk83 on Gadi writes files to a directory (defined in spack-config) that is not writeable by users. Having said that, it is entirely possible for us create another Spack instance that can be used by users that want to build models. I already modified spack-config's spack-enable.bash script to allow such a scenario.

[harshula]

Hi @atteggiani , Thanks for the chat. At the moment, I can see a way where we can reduce the git cloning to only spack-config. Please elaborate on your ideal user experience and I'll see if that is achievable and is less complicated than a single git clone.

[harshula]

Hi @atteggiani , I remembered last night that files related to an environment are stored in $spack:

[root@86f5aa35cc4d spack]# pwd
/opt/spack
[root@86f5aa35cc4d spack]# find -iname 'findmyenvironment'
[root@86f5aa35cc4d spack]# spack env create findmyenvironment
==> Created environment findmyenvironment in: /opt/spack/var/spack/environments/findmyenvironment
==> Activate with: spack env activate findmyenvironment
[root@86f5aa35cc4d spack]# find -iname 'findmyenvironment'
./var/spack/environments/findmyenvironment

I'll see if there's a recommended way to move it outside of $spack. If not, I'm afraid we are stuck with having to clone the spack repository.

[atteggiani]

Hi @harshula, thank you for the chat.
Below I will detail the ideal user experience I thought about.

Ideal user experience

What most users (that need to build a model) would like to do

Most users that require a new model build, will do it because they need to change something in the source code of one or more model components (e.g.: they developed a new convection scheme for the UM, they want to use a custom version of CABLE (embedded in UM), they have changed some physics in MOM, etc.).

Ideal workflow to meet user's needs

My preferred workflow for a user to produce a custom build of an ACCESS-NRI released model is listed below.

Workflow for the first time

1. Load a module to access the right spack executable (and setup any environment variable that is related to spack).

   module load access-spack
   

2. (ONLY IF NEEDED) Run a command that configures spack (one-off step)

   spack-config [--dir <path-to-releases-parent-dir] [--any-other-important-flag]
   

3. Build the executables
   Proceed with the actual build of the executables from the source.

   spack install ... 
   

   (Not sure about the correct options/arguments for this step)

Workflow for the following times

1. Load a module to access the right spack executable (and setup any environment variable that is related to spack).

   module load access-spack
   

2. Build the executables
   Proceed with the actual build of the executables from the source.

   spack install ... 
   

   (Not sure about the correct options/arguments for this step)

For the actual build step, due to my lack of knowledge about spack, I cannot provide a more detailed example.

Summary

The general concept is that the user should be able to build a new executable only by loading the spack module (for the spack executable and its configuration) and running the spack building command.
Of course, in case they want to do any more sofisticated stuff, they can do it in between step 1 (module load) and 2 (spack build), but that would be for "advanced users" that probably cover < 10% of the users that would build a model.

---

What are your thoughts on this workflow?
What are the differences with your workflow that would clone the spack-config repo?
What are the limitations of my workflow in the current implementation of the spack instance (spack, spack-config, spack-packages)?

[harshula]

Hi @atteggiani , It looks like spack/spack#11871 is a blocker for what you want.

[harshula]

Hi @atteggiani , Maybe there is a way, I found:
lib/spack/spack/environment/environment.py:

def env_root_path() -> str:
    """Override default root path if the user specified it"""
    return spack.util.path.canonicalize_path(
        spack.config.get("config:environments_root", default=default_env_path)
    )

[atteggiani]

Hi @atteggiani , It looks like spack/spack#11871 is a blocker for what you want.

Yes I see.
I am not sure all the features in spack/spack#11871 are needed for the worflow I wrote above though.

What do you think the best approach is?

[harshula]

Hi @atteggiani , Can we please have the same preamble as the set-up Spack doc?

!!! danger
    This page is tailored to experienced users and collaborators developing ACCESS models.

[Spack](https://spack.io/about/) is a build-from-source package manager, specifically designed to simplify the installation of scientific software on supercomputers.

To use _Spack_, please familiarise yourself with the [Basic Usage instructions](https://spack.readthedocs.io/en/latest/basic_usage.html) and [Environments](https://spack.readthedocs.io/en/latest/environments.html).

We also recommend that you refer to the [Spack 101 Tutorial](https://spack-tutorial.readthedocs.io/en/latest/).

[atteggiani]

Hi @atteggiani , Can we please have the same preamble as the set-up Spack doc?

!!! danger
    This page is tailored to experienced users and collaborators developing ACCESS models.

[Spack](https://spack.io/about/) is a build-from-source package manager, specifically designed to simplify the installation of scientific software on supercomputers.

To use _Spack_, please familiarise yourself with the [Basic Usage instructions](https://spack.readthedocs.io/en/latest/basic_usage.html) and [Environments](https://spack.readthedocs.io/en/latest/environments.html).

We also recommend that you refer to the [Spack 101 Tutorial](https://spack-tutorial.readthedocs.io/en/latest/).

I added the "danger" admonition, but I don't think we should copy all that text.
The Spack Set Up page will be listed as a prerequisite and that part is in that page, so users will already know it (or have access to it).
There is a small overview about Spack and the purpose of the page in "About".