diff --git a/docs/about/License.md b/docs/about/License.md index 1681b3781..60f548314 100644 --- a/docs/about/License.md +++ b/docs/about/License.md @@ -5,10 +5,19 @@ license][cc-by-human]. The following is a human-readable summary of (and not a substitute for) the [full legal text of the CC BY 4.0 license][cc-by-legal]. -You are free: - -* to **Share**---copy and redistribute the material in any medium or format -* to **Adapt**---remix, transform, and build upon the material +You are free to: + for any purpose, even commercially. @@ -16,22 +25,26 @@ The licensor cannot revoke these freedoms as long as you follow the license terms. Under the following terms: - -* **Attribution**---You must give appropriate credit (mentioning that your work is derived from work that is Copyright © ACCESS-NRI and, where practical, linking to https://www.access-nri.org.au/), provide a [link to the license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. - -* **No additional restrictions**---You may not apply legal terms or -technological measures that legally restrict others from doing -anything the license permits. With the understanding that: - -Notices: - -* You do not have to comply with the license for elements of the - material in the public domain or where your use is permitted by an - applicable exception or limitation. -* No warranties are given. The license may not give you all of the - permissions necessary for your intended use. For example, other - rights such as publicity, privacy, or moral rights may limit how you - use the material. + [cc-by-human]: https://creativecommons.org/licenses/by/4.0/ [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode diff --git a/docs/about/code_of_conduct.md b/docs/about/code_of_conduct.md deleted file mode 100644 index 40f4888b9..000000000 --- a/docs/about/code_of_conduct.md +++ /dev/null @@ -1,7 +0,0 @@ -# Code of Conduct - -ACCESS-Hive is an open community supported effort. For it to be successful it must be a welcoming and inclusive space so that everyone in the community feels able to contribute. - -To ensure this is the case users and contributors to ACCESS-Hive and the ACCESS-Hive Forum are required to abide by the [ACCESS-NRI code of conduct][code-of-conduct]. - -[code-of-conduct]: https://www.access-nri.org.au/community/access-nri-code-of-conduct/ \ No newline at end of file diff --git a/docs/about/contact.md b/docs/about/contact.md index 6aceb3d41..da76a9728 100644 --- a/docs/about/contact.md +++ b/docs/about/contact.md @@ -1,6 +1,6 @@ # Contact - + ACCESS-Hive is an initiative of the Australian Earth-System Simulator (ACCESS-NRI). diff --git a/docs/about/contribute/contribute_on_github.md b/docs/about/contribute/contribute_on_github.md index 564b2d24f..4c7dbbaa5 100644 --- a/docs/about/contribute/contribute_on_github.md +++ b/docs/about/contribute/contribute_on_github.md @@ -15,33 +15,24 @@ -## Let's get started! +## Let's get started! - - git commit -m "Let's 'git' started!!!" - - - - -This documentation is written in Markdown format and is based on the Material for MkDocs documentation framework, which is built on top of MkDocs static site generator. Please refer to this cheatsheet for a quick reference to basic markdown syntax, which is used by Material for MkDocs theme used in this website. - -
- Note: Since, ACCESS-Hive curates useful resources for making comprehensive guides for the ACCESS community, it includes content that is not curated and hosted by ACCESS-NRI. -
- -## Become a member of the ACCESS-Hive GitHub repository - -The ACCESS-Hive user portal is open to receiving contributions from anyone relating to different aspects of the website, including bug fixes, content additions, and enhancement suggestions. The ACCESS-Hive GitHub organisation members would have write access to the ACCESS-Hive repository, and they can contribute by creating their own branches instead of maintaining their individual forks. - -Hence, we encourage you to become a member of the ACCESS-Hive GitHub organisation by replying to this issue and ask to be invited to join the organisation. +This documentation is written in Markdown format and is based on the Material for MkDocs theme, which is built on top of MkDocs static site generator. +
+For a quick reference on how to use Markdown syntax you can refer to the Markdown Cheat Sheet. ## Raise a GitHub Issue -Once you are a member of the ACCESS-Hive GitHub organisation, for all additions or modifications to the ACCESS-Hive site, it is recommended to start by opening an issue in the ACCESS-Hive GitHub repository. Feel free to assign that issue to yourself if you intend to work on that issue. +All contributions need to have an associated Github issue that explains the content and importance of the contribution. +
+To raise an issue, create a New Issue in the ACCESS-Hive Github repository issue page. Feel free to assign that issue to yourself if you intend to work on it. + +## Fork the ACCESS-Hive GitHub repository -## Clone the ACCESS-Hive GitHub repository +After raising a Github issue about your contribution, you need to fork the ACCESS-Hive Github repository. -For cloning this repository onto your local computer, we encourage you to first add your local SSH keys to your GitHub profile. +## Clone the forked ACCESS-Hive GitHub repository locally +For cloning the forked repository onto your local computer, we encourage you to first add your local SSH keys to your GitHub profile. To start with, if you have an existing SSH key, then simply add this key to your github account, and you are all set to clone the repository. In case you don't have the SSH keys set up on your local computer, it's easy to create a new SSH key locally, and then feel free to link this key to your github account. diff --git a/docs/about/contribute/index.md b/docs/about/contribute/index.md index 30bd271d4..8c6c6e684 100644 --- a/docs/about/contribute/index.md +++ b/docs/about/contribute/index.md @@ -1,32 +1,42 @@ # Contribute to ACCESS-Hive - + ACCESS-Hive is an open user portal which hosts the documentation relevant to the Australian Community Climate and Earth System Simulator (ACCESS) community. -Contributions are encouraged from any member of the community regarding any aspect of the **ACCESS-Hive** website (which curates ACCESS documentation and its related resources) or the Hive Forum (used for community discussions). +Contributions are encouraged from any member of the community regarding any aspect of the ACCESS-Hive user portal. ## How can I contribute? -Anyone is welcome to contribute towards improving the **ACCESS-Hive** user portal. The following section lists the contribution tasks that we are most interested in receiving community help with. Please consider helping with one or more tasks below, and we are looking towards receiving your very first contribution for the **ACCESS-Hive**!
- +
- + +
+
+
+ Quick Contribution +
+ + Suggest an idea, propose bug fixes, or flag missing content by raising a GitHub issue. + +
+
+ +
+
- - Contribute on Github! + Write your own content
- Suggest an idea, propose bug fixes, or flag missing content on ACCESS-Hive GitHub repo! + Contribute to the ACCESS-Hive user portal by adding content to the ACCESS-Hive Github repository yourself.
-[^1]: _"How to contribute" sample image source_: Image by pch.vector on Freepik -[^2]: _"Have a question or need help?" sample image source_:Image by pch.vector on Freepik -[^3]: _"Contribute to github?" sample image source_:Image by vectorjuice on Freepik +[^1]: _"How to contribute" sample image source_: Image by pch.vector on Freepik +[^3]: _"Contribute to github?" sample image source_:Image by vectorjuice on Freepik diff --git a/docs/about/index.md b/docs/about/index.md new file mode 100644 index 000000000..be6ebc748 --- /dev/null +++ b/docs/about/index.md @@ -0,0 +1,34 @@ +# About + +
+ +
+ Contacts +
+
Contact
+
+ +
+ ACCESS-NRI Support +
+
User support
+
+ +
+ Contribute +
+
How to contribute
+
+ +
+
+
+
License
+
+ +
+ Code of conduct +
+
Code of conduct
+
+
\ No newline at end of file diff --git a/docs/about/user_support/ask_on_forum.md b/docs/about/user_support/ask_on_forum.md index 48d917f30..d76ec4a6f 100644 --- a/docs/about/user_support/ask_on_forum.md +++ b/docs/about/user_support/ask_on_forum.md @@ -30,6 +30,4 @@ After a discussion topic is posted on the forum, the ACCESS-NRI and community ex Request is solved. - - -We highly appreciate any contributions received from our community and do our best to engage the wider community through shared Hive Forum activities. Additionally, if you would like to make contributions on GitHub, please consider following these guidelines before submitting a new feature request, improvement ideas or bug reports. We would love to have your contributions onboard for the ACCESS-Hive GitHub repo! + \ No newline at end of file diff --git a/docs/about/user_support/index.md b/docs/about/user_support/index.md index 3eca94dcd..90be61cc5 100644 --- a/docs/about/user_support/index.md +++ b/docs/about/user_support/index.md @@ -2,7 +2,7 @@ On this page we answer frequently asked questions (FAQs), and also give additional information for support, in case your question is not yet answered. -## Frequently Asked Questions +## Frequently Asked Questions (FAQ) Click on the questions to unfold the answers. @@ -55,7 +55,7 @@ Click on the questions to unfold the answers. Go to our [**Model Data**](../model_evaluation/model_evaluation_model_catalogs/index.md) section on the ACCESS-Hive to learn how to find and access model data. - In any case, you need to have access to the specific projects and NCI itself in order to read the data. We explain this on our [**Getting Started Pages**](../getting_started/index.md). + In any case, you need to have access to the specific projects and NCI itself in order to read the data. We explain this on our [**Getting Started Pages**](../getting_started/first_steps.md). ??? abstract "What is the difference between _teams_ and _working groups_?" diff --git a/docs/assets/ACCESS_logo_rgb.png b/docs/assets/ACCESS_logo_rgb.png new file mode 100755 index 000000000..700b3529b Binary files /dev/null and b/docs/assets/ACCESS_logo_rgb.png differ diff --git a/docs/assets/are_logo.svg b/docs/assets/are_logo.svg new file mode 100644 index 000000000..6425555c3 --- /dev/null +++ b/docs/assets/are_logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/code_of_conduct.jpeg b/docs/assets/code_of_conduct.jpeg new file mode 100644 index 000000000..83c7eee4b Binary files /dev/null and b/docs/assets/code_of_conduct.jpeg differ diff --git a/docs/assets/contact_logo.png b/docs/assets/contact_logo.png new file mode 100644 index 000000000..4407a191f Binary files /dev/null and b/docs/assets/contact_logo.png differ diff --git a/docs/assets/contribute_image.png b/docs/assets/contribute_image.png new file mode 100644 index 000000000..2fcad8c44 Binary files /dev/null and b/docs/assets/contribute_image.png differ diff --git a/docs/assets/first_steps_logo.png b/docs/assets/first_steps_logo.png new file mode 100644 index 000000000..b96531a6a Binary files /dev/null and b/docs/assets/first_steps_logo.png differ diff --git a/docs/assets/jupyterlab_plus_button.png b/docs/assets/jupyterlab_plus_button.png new file mode 100644 index 000000000..6afe68142 Binary files /dev/null and b/docs/assets/jupyterlab_plus_button.png differ diff --git a/docs/assets/launch_are_jupyterlab.gif b/docs/assets/launch_are_jupyterlab.gif new file mode 100644 index 000000000..15bc1847c Binary files /dev/null and b/docs/assets/launch_are_jupyterlab.gif differ diff --git a/docs/assets/launch_are_vdi_desktop.gif b/docs/assets/launch_are_vdi_desktop.gif new file mode 100644 index 000000000..fe6ca44ea Binary files /dev/null and b/docs/assets/launch_are_vdi_desktop.gif differ diff --git a/docs/assets/run_access_cm/Cylc GUI.png b/docs/assets/run_access_cm/Cylc_GUI.png similarity index 100% rename from docs/assets/run_access_cm/Cylc GUI.png rename to docs/assets/run_access_cm/Cylc_GUI.png diff --git a/docs/assets/run_access_cm/Cylc_GUI_are.png b/docs/assets/run_access_cm/Cylc_GUI_are.png new file mode 100644 index 000000000..21defd79d Binary files /dev/null and b/docs/assets/run_access_cm/Cylc_GUI_are.png differ diff --git a/docs/assets/run_access_cm/Rose_GUI_are.png b/docs/assets/run_access_cm/Rose_GUI_are.png new file mode 100644 index 000000000..d4a95e46e Binary files /dev/null and b/docs/assets/run_access_cm/Rose_GUI_are.png differ diff --git a/docs/assets/run_access_cm/investigate_error_gui_are.gif b/docs/assets/run_access_cm/investigate_error_gui_are.gif new file mode 100644 index 000000000..9c840da28 Binary files /dev/null and b/docs/assets/run_access_cm/investigate_error_gui_are.gif differ diff --git a/docs/assets/run_access_cm/launch_are_vdi.gif b/docs/assets/run_access_cm/launch_are_vdi.gif new file mode 100644 index 000000000..a8d3c9ff5 Binary files /dev/null and b/docs/assets/run_access_cm/launch_are_vdi.gif differ diff --git a/docs/assets/run_access_cm/open_are_vdi_terminal.gif b/docs/assets/run_access_cm/open_are_vdi_terminal.gif new file mode 100644 index 000000000..937a3f81e Binary files /dev/null and b/docs/assets/run_access_cm/open_are_vdi_terminal.gif differ diff --git a/docs/assets/run_access_cm/rose_change_project_are.gif b/docs/assets/run_access_cm/rose_change_project_are.gif new file mode 100644 index 000000000..217b9a05c Binary files /dev/null and b/docs/assets/run_access_cm/rose_change_project_are.gif differ diff --git a/docs/assets/run_access_cm/rose_change_run_length_are.gif b/docs/assets/run_access_cm/rose_change_run_length_are.gif new file mode 100644 index 000000000..d430951f7 Binary files /dev/null and b/docs/assets/run_access_cm/rose_change_run_length_are.gif differ diff --git a/docs/assets/session_delete_button.png b/docs/assets/session_delete_button.png new file mode 100644 index 000000000..59968d8a8 Binary files /dev/null and b/docs/assets/session_delete_button.png differ diff --git a/docs/assets/user_support_image.png b/docs/assets/user_support_image.png new file mode 100644 index 000000000..44f44b9a3 Binary files /dev/null and b/docs/assets/user_support_image.png differ diff --git a/docs/community_resources/community_working_groups.md b/docs/community_resources/community_working_groups.md index 75b9f2807..1d5fc56e7 100644 --- a/docs/community_resources/community_working_groups.md +++ b/docs/community_resources/community_working_groups.md @@ -6,37 +6,37 @@ The working group activities are coordinated through the instructions on the ACCESS-NRI website.
- +
Atmosphere
Atmospheric Modelling
- +
Atmosphere
Land Surface Modelling
- +
Atmosphere
COSIMA
(Ocean and Sea-Ice)
- +
Atmosphere
Forecasting and Prediction
- +
Atmosphere
Earth System Modelling
- +
Atmosphere
diff --git a/docs/community_resources/glossaries.md b/docs/community_resources/glossaries.md index e4145d6e0..2d2640f38 100644 --- a/docs/community_resources/glossaries.md +++ b/docs/community_resources/glossaries.md @@ -1,10 +1,38 @@ # Glossary and Useful Terms -Here you can find a compilation of common terms and acronyms used by the Australian Community Climate and Earth System Simulator (ACCESS) community: - - [ACCESS-NRI Glossary](https://www.access-nri.org.au/community/access-glossary/): This includes common terms and acronyms used by the ACCESS community in research and modelling of past, present and future climate, weather and Earth-Systems. - - [IPCC Acronyms](https://www.ipcc.ch/site/assets/uploads/sites/2/2022/06/SR15_AnnexI.pdf): Contains a comprehensive list of acronyms published in the scientific report SR15 of the Intergovernmental Panel on Climate Change (IPCC). The IPCC is the United Nations body for assessing the science related to climate change. - - [CSSR Acronyms and Units](https://science2017.globalchange.gov/chapter/appendix-d/): The Climate Science Special Report (CSSR) is an assessment of the science of climate change with particular focus on the United States. \ No newline at end of file +
+ +
+ Find img +
+
+ ACCESS-NRI Glossary + + Common terms and acronyms used by the Australian Community Climate and Earth System Simulator (ACCESS) community. + +
+
+ +
+ Find img +
+
+ IPCC Glossary + + List of terms and acronyms published in the latest Intergovernmental Panel on Climate Change (IPCC) report "SR15". The IPCC is the United Nations body for assessing the science related to climate change. + +
+
+ +
+ Find img +
+
+ CSSR Acronyms and Units + + The Climate Science Special Report (CSSR) is an assessment of the science of climate change with particular focus on the United States. + +
+
+
\ No newline at end of file diff --git a/docs/css/access-nri.css b/docs/css/access-nri.css index a09277370..de3ff025f 100644 --- a/docs/css/access-nri.css +++ b/docs/css/access-nri.css @@ -26,19 +26,12 @@ --md-primary-bg-color--light: rgba(var(--primary-bg-color),0.5); /* search bar 'Search' text */ --md-accent-fg-color--transparent: rgba(var(--nri-blue-color),.05); /* navigation bar little arrows hover */ --md-accent-bg-color: rgb(var(--tab-text-color)); /* back to top button text hover */ - --md-code-hl-color: rgba(255,255,0,.5); - --md-code-hl-number-color: #d52a2a; + --md-code-hl-color: purple; + --md-code-hl-string-color: #1c7d4d; + --md-code-hl-keyword-color: #ff6fb2; --md-code-hl-special-color: #db1457; - --md-code-hl-function-color: #a846b9; + --md-code-hl-function-color: var(--nri-blue); --md-code-hl-constant-color: #6e59d9; - --md-code-hl-keyword-color: #3f6ec6; - --md-code-hl-string-color: #1c7d4d; - --md-code-hl-name-color: var(--md-code-fg-color); - --md-code-hl-operator-color: var(--md-default-fg-color--light); - --md-code-hl-punctuation-color: var(--md-default-fg-color--light); - --md-code-hl-comment-color: var(--md-default-fg-color--light); - --md-code-hl-generic-color: var(--md-default-fg-color--light); - --md-code-hl-variable-color: var(--md-default-fg-color--light); --md-typeset-mark-color: rgba(var(--nri-orange-color),.4); /* marked text ( tag)*/ --md-typeset-del-color: rgba(245,80,61,.15); /* deleted text ( tag) */ --md-typeset-ins-color: rgba(11,213,112,.15); /* inserted text ( tag) */ @@ -68,6 +61,8 @@ --not-owned: rgb(var(--not-owned-color)); /* Not supported warnings */ --info-color: var(--nri-light-blue-color); /* Color for info warnings */ --info: rgb(var(--info-color)); /* Info warnings */ + --faq-color: var(--nri-blue-color); /* Color for FAQ warnings */ + --faq: rgb(var(--faq-color)); /* FAQ warnings */ } [data-md-color-scheme="custom-dark"] { @@ -86,6 +81,13 @@ --md-accent-fg-color: var(--nri-blue); /* link text hover */ --md-code-fg-color: var(--md-default-fg-color); /* code element text */ --md-code-bg-color: rgb(41, 41, 41); /* code element background */ + --md-code-hl-name-color: var(--md-code-fg-color); + --md-code-hl-operator-color: var(--md-code-fg-color); + --md-code-hl-punctuation-color: var(--md-code-fg-color); + --md-code-hl-comment-color: rgba(var(--default-fg-color), 0.5); + --md-code-hl-number-color: var(--nri-orange); + --md-code-hl-generic-color: var(--md-code-fg-color); + --md-code-hl-variable-color: var(--md-code-fg-color); --md-typeset-kbd-color: rgb(39, 39, 39); /* keyboard key background ( tag) */ --md-typeset-kbd-accent-color: rgb(126, 126, 126, .16); /* keyboard key inner border ( tag) */ --md-typeset-kbd-border-color: rgb(30, 30, 30); /* text as keyboard outer border ( tag) */ @@ -115,6 +117,13 @@ --md-accent-fg-color: var(--nri-blue); /* link text hover */ --md-code-fg-color: rgb(33, 36, 44); /* code element text */ --md-code-bg-color: #dedede; /* code element background */ + --md-code-hl-name-color: var(--md-code-fg-color); + --md-code-hl-operator-color: var(--md-code-fg-color); + --md-code-hl-punctuation-color: var(--md-code-fg-color); + --md-code-hl-comment-color: rgba(var(--default-fg-color), 0.5); + --md-code-hl-number-color: #d58d15; + --md-code-hl-generic-color: var(--md-code-fg-color); + --md-code-hl-variable-color: var(--md-code-fg-color); --md-typeset-kbd-color: rgb(226, 226, 226); /* keyboard key background ( tag) */ --md-typeset-kbd-accent-color: rgb(255, 255, 255, .78); /* keyboard key inner border ( tag) */ --md-typeset-kbd-border-color: rgb(212, 212, 212); /* text as keyboard outer border ( tag) */ @@ -194,7 +203,7 @@ .card-text-container { color: var(--md-default-fg-color); - font-size: 1.4em; + font-size: 1.2em; display: flex; flex-direction: column; align-items: center; @@ -222,7 +231,7 @@ height: 30%; flex-grow: 0; flex-shrink: 0; - font-size: 12cqi; + font-size: 10cqi; padding: 3.5%; } @@ -348,6 +357,7 @@ h1.homepage { /* Lower text on all homepage cards*/ :is(.homepage-buttons,.homepage-navigation) .card-text-container { color: var(--tab-text); + font-size: 12cqi; } :is(.homepage-buttons,.homepage-navigation) .card-text-container > * { border-radius: 0.4rem; @@ -434,11 +444,15 @@ h1.homepage { background-color: rgba(var(--info-color),0.2); } -/* Transparent background for warnings */ -.md-typeset details { +/* Abstract warnings (used for FAQs */ +.md-typeset :is(.admonition,details):is(.abstract) { + border-color: var(--faq); background-color: transparent; font-size: 1em; } +.md-typeset :is(.abstract)>:is(.admonition-title,summary) { + background-color: rgba(var(--faq-color),0.2); +} /* =============================================================== @@ -762,7 +776,7 @@ ul:not([class^='md-']) li ul li ul li { /* =============================================================== Code block */ -pre:has(code) { +pre { display: flow-root !important; text-align: left !important; padding: 0 !important; @@ -779,10 +793,6 @@ pre>code { pre > button:is(:hover,:focus).md-clipboard { color: var(--md-primary-fg-color--dark) !important; } -/* Copy icon not getting white when hovering over the code element */ -pre:has(code):hover > button { - color: var(--md-default-fg-color--lightest) !important; -} /* =============================================================== Terminal animations @@ -834,10 +844,12 @@ pre:has(code):hover > button { position: relative; box-shadow: 0 -0.05rem var(--md-default-fg-color--lightest) inset; display: flex; + flex-wrap: wrap; width: fit-content; overflow: auto; margin-top: 1em; gap: 1px; + font-size: 0.9em; } /* Style the buttons that are used to open the tab content */ @@ -847,7 +859,6 @@ pre:has(code):hover > button { border-radius: 0.6rem 0.6rem 0 0; cursor: pointer; flex-shrink: 0; - font-size: .64rem; font-weight: 700; padding: 0.78125em 1.25em 0.625em; scroll-margin-inline-start: 1rem; @@ -877,9 +888,13 @@ pre:has(code):hover > button { .tabContents > .activeTabContent { display: block; - margin-bottom: 1em; } +.version-tabs { + margin-bottom: 0.3rem; + font-size: 1.2em; + width: 100%; +} /* =============================================================== Notes (!! icon marks) */ @@ -889,7 +904,7 @@ pre:has(code):hover > button { background-color: var(--note-bg); border-radius: 0.3rem; padding: 0.2em 0.3em 0.2em 1.5em; - margin-bottom: 0.8em; + margin: 0.3em 0 0.8em 0; } .note::before { @@ -954,6 +969,7 @@ img.intro-img { /* Gifs, videos and example images (For example the ones in 'how to run' a model */ .example-img { + display: block; width: 100%; border-radius: 0.6rem; } @@ -977,7 +993,7 @@ img.intro-img { /* Add padding to image container */ .with-padding { - padding: 0.4rem; + padding: 0.4rem !important; } .bold { @@ -986,15 +1002,15 @@ img.intro-img { /* image cover */ .img-cover { - object-fit: cover; + object-fit: cover !important; } .img-contain { - object-fit: contain; + object-fit: contain !important; } .large-text { - font-size: 1.4em; + font-size: 1.4em !important; } .nri-link-color { @@ -1090,7 +1106,7 @@ img.intro-img { .horizontal-card > .card-text-container { height: 30%; flex: 0 0 auto; - font-size: 12cqi; + font-size: 10cqi; font-weight: 600; padding: 3.5%; } @@ -1196,7 +1212,7 @@ img.intro-img { height: 11rem; } } -@media screen and (width <= 550px) { +@media screen and (width <= 600px) { .vertical-card { width: 40%; } @@ -1214,7 +1230,7 @@ img.intro-img { .horizontal-card > .card-text-container { height: 30%; flex: 0 0 auto; - font-size: 12cqi; + font-size: 10cqi; font-weight: 600; padding: 3.5%; } diff --git a/docs/getting_started/are.md b/docs/getting_started/are.md new file mode 100644 index 000000000..ada5a4491 --- /dev/null +++ b/docs/getting_started/are.md @@ -0,0 +1,223 @@ +# Australian Research Environment (ARE) + +ARE is a web-based graphical interface for performing your computational research, provided by NCI. +
+ARE can give you access to NCI’s Gadi supercomputer and data collections. + + +There are multiple applications included in ARE, but the two most used for ACCESS-related activities are Virtual Desktop (VDI) and JupyterLab. + +## Start an ARE session + +
+ + +
+ +
+ +
+ To start an ARE VDI session go to the ARE VDI Desktop page. +
+ +
+ To start an ARE JupyterLab session go to the ARE JupyterLab page. +
+
+ + +### Session options +Launching an ARE session is similar to submitting an interactive PBS job that enables you to connect to a Gadi computing node. +
+Therefore, there are multiple PBS directives and other options you can select: +
    +
  • + Walltime (hours) +
    + Number of hours your VDI session will run for (unless manually ended earlier). +
    + The maximum number of hours an ARE session can run for depends on the selected Queue. For more information, check Gadi Queue Limits. +
    + Once the session ends any operation still in progress on the session's computing node(s) will be immediately terminated. +
    +
  • +
  • + Queue +
    + Gadi queue that your session will be scheduled in. For more information check Gadi Queue Structure. +
  • +
  • + Compute Size +
    + Amount of resources (CPUs, Memory, etc.) available to your session. +
    + You can either choose a pre-configured option, or select a custom one (e.g., cpus=6 mem=40G). +
  • +
  • + Project +
    + The NCI project the ARE session will be charged to. +
    + You must be a member of the specified project. +
    + The specified project must have allocated Service Units (SU). +
    + For more information, check how to join relevant NCI projects. +
    +
  • +
  • + Storage +
    + /g/data (inserted as gdata/<project-ID>) and /scratch (inserted as scratch/<project-ID>) data storage projects that will be available to the session. +
    + In ARE, data storage locations need to be explicitly defined. This means that you need to insert any /g/data and /scratch project folders you want to execute data I/O operations from. +
    + Multiple storage projects are separated by a plus (+) (e.g., gdata/tm70+gdata/hh5+scratch/xp65). +
    + Generally, you need to be a member of the specified projects to access their storage data. +
    + If you try to access data from a project folder not included in the session's storage, you will get an error similar to the following: +
    + <cmd>: cannot access '</path/to/file>': No such file or directory +
    +
  • +
  • + Software +
    + Software licenses that are requested for your ARE session. Leave blank if no license needed. +
    + Multiple licenses are separated by a colon (:). +
  • +

    Advanced options

    + +
    + +
    +
    + +
    +
  • + Extra arguments +
    + Additional arguments to pass on the JupyterLab command line (e.g., --debug, --log-level=INFO) +
  • +
  • + Module directories +
    + Include module directories. +
    + It is the eqivalent of module use </path/to/module/directory> run on the command line. +
    + You also need to include the project directory of each module directory in the Storage option. +
    +
  • +
  • + Modules +
    + Include modules. + It is the equivalent of module load <module-name> run on the command line. +
    + If the module is not inside Gadi's default module directory /apps/Modules/modulefiles, you need to include the module directory in the Module directories option. +
    +
  • +
  • + Python or Conda virtual environment base +
    + Path to a Python or conda base environment to be activated for the JupyterLab session. +
    + It is the equivalent of source <path/to/environment/bin/activate> run on the command line. +
    + You also need to include the project directory of the virtual environment in the Storage option. +
    +
  • +
  • + Conda environment +
    + Name of a specific conda environment to be activated for the JupyterLab session. +
    + It is the equivalent of conda activate <environment-name> run on the command line. +
    + You need to include the path to the conda base environment in the Python or Conda virtual environment base option. +
    +
  • +
    +
    + +
  • + Environment variables +
    + Environment variables passed to the session. Identical to the -v PBS directive. +
    + Multiple environment variables are separated by a comma (,). +
  • +
  • + Jobfs size +
    + The maximum amount of local disk available to the session. +
    + If missing, it is automatically set to 100MB. +
  • +
  • + PBS flags +
    + Extra PBS directives to be used for the ARE job submission. +
  • +
  • + Pre-script +
    + A script or executable that will be run just before starting the ARE session. +
  • +
+ +### Launch the session +
    +
  1. + Click on the Launch button to launch the session. + You will be prompted to your Interactive Sessions page and you will see your last requested session at the top. +
  2. +
  3. + +
    + +
    + Wait until your session starts and then click on the Launch VDI Desktop button to open a new tab with the VDI interface. +
    + Inside the VDI interface, you can open the terminal by clicking on the black terminal icon at the top of the window. +
    + +
    + Wait until your session starts and then click on the Open JupyterLab button to open a new tab with the JupyterLab interface. +
    + Inside the JupyterLab interface, you can open a new notebook by clicking on the Python3 Notebook button in the Launcher panel (to open a new Laucher panel, click on the plus button Plus button next to your current tab). +
    +
    + +
  4. +
    + +
    + Launch ARE VDI Desktop +
    + +
    + Launch ARE JupyterLab +
    +
    +
+ +## Delete an ARE session +You can delete a session before its automatic expiration (based on the specified Walltime) by clicking on the session's Delete button Session Delete button in the Interactive Sessions page. + +
+
References
+ \ No newline at end of file diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md new file mode 100644 index 000000000..ffd3c4dd9 --- /dev/null +++ b/docs/getting_started/first_steps.md @@ -0,0 +1,270 @@ +# First Steps + +The steps in this section are aimed at new users who would like to do any of the following tasks: + +- Run their own experiment +- Analyse model data outputs +- Browse observational data catalogues +- Evaluate model performance +- Perform other tasks involving ACCESS models or evaluation tools +
+ +## Create an NCI user account +Most of the data and models you will need are available at the National Computing Infrastructure (NCI) . +
+To access these, you need an NCI account. If you do not have one, sign up here. +
+You will need an institutional email address with an organisation that allows access to NCI (e.g., an Australian university, ACCESS-NRI, CSIRO, BoM, CLEX, etc.). +
+Once you sign up, you will be assigned a username (e.g., `ab1234`). +
+ +## Join relevant NCI projects + +NCI provides multiple services that are necessary for climate research. These include the access to supercomputing resources, data storage, and data collections management. + +For technical reasons, to access either of these services you need to join a specific `project`. +Each project has an ID (e.g. `xp65`), which is what the term project actually refers to. + +If you are interested in datasets and data collections, you can browse the NCI Data Catalogue and follow the NCI Data Catalogue User Guide. + +To perform computations on Gadi instead, you need to join a project with computing resources, also called Service Units (SU). The project ID will be provided by your supervisor, research project or institution. + +To join a project, search for it on NCI website and request membership. +
+ The first project you join will become your default one. If you would like to change this, check out how to change your default project on Gadi. +
+ +There are several NCI projects that may be relevant to you, depending on the tasks you want to carry out. +
+For tasks supported by ACCESS-NRI (e.g., running a supported model configuration, using a supported model evaluation tool, etc.), you will find a list of relevant projects to join in the pages relative to each respective task. + +
+ +## Login to Gadi +Operations involving model runs and data collections take place on the Gadi supercomputer. + +Before you login to Gadi, you need to possess the following prerequisites: +
    +
  • Internet connection
  • +
  • + UNIX-like terminal +
    + Linux and MacOS operative systems already have a built-in UNIX-like terminal. +
    + Windows users can install Windows Subsystems for Linux (WSL). +
    + Alternatively, you can login through the ARE Gadi Terminal. +
    + However, it is recommended that you connect to Gadi from your local machine's terminal without using ARE. +
    +
  • +
+ +To login to Gadi using SSH, on your **local machine's terminal** run the following command, replacing <your-NCI-username> with your NCI username (e.g., ab1234): +
ssh <your-NCI-username>@gadi.nci.org.au
+You will be prompted to enter your NCI password, and then you will be connected to Gadi: + + ssh <your-NCI-username>@gadi.nci.org.au + <NCI-username>@gadi.nci.org.au's password: + ############################################################################### + #           Welcome to the NCI National Facility!             # + #    This service is for authorised clients only. It is a criminal      # + #    offence to:                                      # + #          - Obtain access to data without permission;                 # + #          - Damage, delete, alter or insert data without permission;  # + #    Use of this system requires acceptance of the Conditions of Use;    # + #    published at http://nci.org.au/users/nci-terms-and-conditions-access; # + ############################################################################### + |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | + =============================================================================== + =============================================================================== + + + +### Auto login +To simplify the login and avoid being prompted every time to enter your NCI password, follow these steps: +
    +
  1. + Create an SSH key +
    + To create an SSH key on your local machine, run: +
    ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi
    + You will be prompted to create a passphrase linked to the SSH key, which you will enter twice: + + ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi + Generating public/private rsa key pair. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in <$HOME>/.ssh/id_gadi + Your public key has been saved in /Users/davide/.ssh/id_gadi.pub + The key fingerprint is: + SHA256:<fingerprint-code> <$USER@hostname> + The key's randomart image is: + +---[RSA 4096]----+ + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + +----[SHA256]-----+ + +
    + For security reasons, it is recommended to enter a passphrase rather than leave it empty. +
    + As you will see in the next step, you will not need to enter the passphrase every time you login to Gadi. +
    +
  2. +
  3. + Add the SSH key to the SSH-agent +
    + An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server. +
    + To add the SSH key to the SSH-agent: +
      +
    1. + On your local machine, start the SSH-agent by running: +
      eval "$(ssh-agent -s)"
      + + eval "$(ssh-agent -s)" + Agent pid <agent-PID> + +
    2. +
    3. + Add your SSH key to the SSH-agent by running: + +
      + + +
      + +
      + +
      +
      ssh-add --apple-use-keychain ~/.ssh/id_gadi
      + You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: + + ssh-add --apple-use-keychain ~/.ssh/id_gadi + Enter passphrase for <$HOME>/.ssh/id_gadi: + Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> + +
      + If you are using a MacOS version prior to Monterey (12.0), substitute the --apple-use-keychain flag with -K. +
      +
      + +
      +
      ssh-add ~/.ssh/id_gadi
      + You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: + + ssh-add ~/.ssh/id_gadi + Enter passphrase for <$HOME>/.ssh/id_gadi: + Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> + +
      +
      + +
    4. +
    +
  4. +
  5. + Create/Update the SSH config file +
    + The ~/.ssh/config is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all. +
    + To create an SSH config file, run the following command on your local machine: +
    touch ~/.ssh/config
    +
    + If you already have an existing ~/.ssh/config file, the above command will not have any effect. +
    + The following lines should be added to your ~/.ssh/config to describe the SSH configuration for Gadi (replace <your-NCI-username> with your NCI username, e.g., ab1234): +
    Host gadi
    +    Hostname gadi.nci.org.au
    +    User <your-NCI-username>
    +    ForwardX11 true
    +    ForwardX11Trusted yes
    +    IdentityFile ~/.ssh/id_gadi
    +    AddKeysToAgent yes
    +    UseKeychain yes
    +
    + If you already have an existing ~/.ssh/config file which contains configurations for every Host (e.g., by using Host *), make sure you delete any of the keywords present in that SSH configuration from the Gadi configuration above. +
    +
    +
  6. +
  7. + Add the SSH key to the authorised keys +
    + To enable automatic connection to a server, that server needs to recognise the SSH key as authorised. The list of authorised keys for a certain server is stored in the file ~/.ssh/authorized_keys. +
    + To add the newly created SSH key as an authorised key for Gadi, run the following command from your local machine: +
    var=$( cat ~/.ssh/id_gadi.pub ) && ssh gadi "echo $var >> .ssh/authorized_keys"
    +
    + Make sure to use double quotes " in the above command. +
    + You will be prompted to enter your NCI password. If you did all of the above steps correctly, this should be the last time you need to do so. +
  8. +
+Once you complete all the above steps, you should be able to connect to Gadi from your **local machine's terminal** simply by running: +
ssh gadi
+ +### Change default project on Gadi +It is recommended that you check what your default project on Gadi is set to. The default project should be set to the computational project you will most likely use to run simulations/evaluations and store data. +
+You can check which is your default project by logging into Gadi and running: +
echo $PROJECT
+To change your default project on Gadi, you need to manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file. +
+Alternatively, you can run the following command on Gadi's terminal: +
sed "s/\(PROJECT \).*/\1<new-default-project>/" ~/.config/gadi-login.conf
+Once this is done, exit from Gadi and log back in. +
+For example, if you want to change your default project to `tm70` on Gadi: + + echo $PROJECT + <old-default-project> + sed "s/\(PROJECT \).*/\1tm70/" ~/.config/gadi-login.conf + exit + logout + Connection to gadi.nci.org.au closed. + ssh gadi + ############################################################################### + #           Welcome to the NCI National Facility!             # + #    This service is for authorised clients only. It is a criminal      # + #    offence to:                                      # + #          - Obtain access to data without permission;                 # + #          - Damage, delete, alter or insert data without permission;  # + #    Use of this system requires acceptance of the Conditions of Use;    # + #    published at http://nci.org.au/users/nci-terms-and-conditions-access; # + ############################################################################### + |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | + =============================================================================== + =============================================================================== + echo $PROJECT + tm70 + +
+ +
References
+ diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 089e1a85d..02f606d64 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -1,268 +1,20 @@ ---- -hide: - - navigation ---- # Getting Started -The steps in this section are aimed at new users who would like to do any of the following tasks: - -- Run their own experiment -- Analyse model data outputs -- Browse observational data catalogues -- Evaluate model performance -- Perform other tasks involving ACCESS models or evaluation tools -
- -## Create an NCI user account -Most of the data and models you will need are available at the National Computing Infrastructure (NCI) . -
-To access these, you need an NCI account. If you do not have one, sign up here. -
-You will need an institutional email address with an organisation that allows access to NCI (e.g., an Australian university, ACCESS-NRI, CSIRO, BoM, CLEX, etc.). -
-Once you sign up, you will be assigned a username (e.g., `ab1234`). -
- -## Join relevant NCI projects - -NCI provides multiple services that are necessary for climate research. These include the access to supercomputing resources, data storage, and data collections management. - -For technical reasons, to access either of these services you need to join a specific `project`. -Each project has an ID (e.g. `xp65`), which is what the term project actually refers to. - -If you are interested in datasets and data collections, you can browse the NCI Data Catalogue and follow the NCI Data Catalogue User Guide. - -To perform computations on Gadi instead, you need to join a project with computing resources. The project ID will be provided by your supervisor, research project or institution. - -To join a project, search for it on NCI website and request membership. -
- The first project you join will become your default one. If you would like to change this, check out how to change your default project on Gadi. -
- -There are several NCI projects that may be relevant to you, depending on the tasks you want to carry out. -
-For tasks supported by ACCESS-NRI (e.g., running a supported model configuration, using a supported model evaluation tool, etc.), you will find a list of relevant projects to join in the pages relative to each respective task. - -
- -## Login to Gadi -Operations involving model runs and data collections take place on the Gadi supercomputer. - -Before you login to Gadi, you need to possess the following prerequisites: -
    -
  • Internet connection
  • -
  • - UNIX-like terminal -
    - Linux and MacOS operative systems already have a built-in UNIX-like terminal. -
    - Windows users can install Windows Subsystems for Linux (WSL). -
    - Alternatively, you can login through the ARE Gadi Terminal. -
    - However, it is recommended that you connect to Gadi from your local machine's terminal without using ARE. -
    -
  • -
- -To login to Gadi using SSH, on your **local machine's terminal** run the following command, replacing <your-NCI-username> with your NCI username (e.g., ab1234): -
ssh <your-NCI-username>@gadi.nci.org.au
-You will be prompted to enter your NCI password, and then you will be connected to Gadi: - - ssh <your-NCI-username>@gadi.nci.org.au - <NCI-username>@gadi.nci.org.au's password: - ############################################################################### - #           Welcome to the NCI National Facility!             # - #    This service is for authorised clients only. It is a criminal      # - #    offence to:                                      # - #          - Obtain access to data without permission;                 # - #          - Damage, delete, alter or insert data without permission;  # - #    Use of this system requires acceptance of the Conditions of Use;    # - #    published at http://nci.org.au/users/nci-terms-and-conditions-access; # - ############################################################################### - |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | - =============================================================================== - =============================================================================== - - - -### Auto login -To simplify the login and avoid being prompted every time to enter your NCI password, follow these steps: -
    -
  1. - Create an SSH key -
    - To create an SSH key on your local machine, run: -
    ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi
    - You will be prompted to create a passphrase linked to the SSH key, which you will enter twice: - - ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi - Generating public/private rsa key pair. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in <$HOME>/.ssh/id_gadi - Your public key has been saved in /Users/davide/.ssh/id_gadi.pub - The key fingerprint is: - SHA256:<fingerprint-code> <$USER@hostname> - The key's randomart image is: - +---[RSA 4096]----+ - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - +----[SHA256]-----+ - -
    - For security reasons, it is recommended to enter a passphrase rather than leave it empty. -
    - As you will see in the next step, you will not need to enter the passphrase every time you login to Gadi. -
    -
  2. -
  3. - Add the SSH key to the SSH-agent -
    - An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server. -
    - To add the SSH key to the SSH-agent: -
      -
    1. - On your local machine, start the SSH-agent by running: -
      eval "$(ssh-agent -s)"
      - - eval "$(ssh-agent -s)" - Agent pid <agent-PID> - -
    2. -
    3. - Add your SSH key to the SSH-agent by running: - -
    4. -
    -
  4. -
  5. - Create/Update the SSH config file -
    - The ~/.ssh/config is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all. -
    - To create an SSH config file, run the following command on your local machine: -
    touch ~/.ssh/config
    -
    - If you already have an existing ~/.ssh/config file, the above command will not have any effect. -
    - The following lines should be added to your ~/.ssh/config to describe the SSH configuration for Gadi (replace <your-NCI-username> with your NCI username, e.g., ab1234): -
    Host gadi
    -    Hostname gadi.nci.org.au
    -    User <your-NCI-username>
    -    ForwardX11 true
    -    ForwardX11Trusted yes
    -    IdentityFile ~/.ssh/id_gadi
    -    AddKeysToAgent yes
    -    UseKeychain yes
    -
    - If you already have an existing ~/.ssh/config file which contains configurations for every Host (e.g., by using Host *), make sure you delete any of the keywords present in that SSH configuration from the Gadi configuration above. -
    -
    -
  6. -
  7. - Add the SSH key to the authorised keys -
    - To enable automatic connection to a server, that server needs to recognise the SSH key as authorised. The list of authorised keys for a certain server is stored in the file ~/.ssh/authorized_keys. -
    - To add the newly created SSH key as an authorised key for Gadi, run the following command from your local machine: -
    var=$( cat ~/.ssh/id_gadi.pub ) && ssh gadi "echo $var >> .ssh/authorized_keys"
    -
    - Make sure to use double quotes " in the above command. -
    - You will be prompted to enter your NCI password. If you did all of the above steps correctly, this should be the last time you need to do so. -
  8. -
-Once you complete all the above steps, you should be able to connect to Gadi from your **local machine's terminal** simply by running: -
ssh gadi
- -### Change default project on Gadi -It is recommended that you check what your default project on Gadi is set to. The default project should be set to the computational project you will most likely use to run simulations/evaluations and store data. -
-You can check which is your default project by logging into Gadi and running: -
echo $PROJECT
-To change your default project on Gadi, you need to manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file. -
-Alternatively, you can run the following command on Gadi's terminal: -
sed "s/\(PROJECT \).*/\1<new-default-project>/" ~/.config/gadi-login.conf
-Once this is done, exit from Gadi and log back in. -
-For example, if you want to change your default project to `tm70` on Gadi: - - echo $PROJECT - <old-default-project> - sed "s/\(PROJECT \).*/\1tm70/" ~/.config/gadi-login.conf - exit - logout - Connection to gadi.nci.org.au closed. - ssh gadi - ############################################################################### - #           Welcome to the NCI National Facility!             # - #    This service is for authorised clients only. It is a criminal      # - #    offence to:                                      # - #          - Obtain access to data without permission;                 # - #          - Damage, delete, alter or insert data without permission;  # - #    Use of this system requires acceptance of the Conditions of Use;    # - #    published at http://nci.org.au/users/nci-terms-and-conditions-access; # - ############################################################################### - |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | - =============================================================================== - =============================================================================== - echo $PROJECT - tm70 - -
- -
References
-
+ + +
+ ARE +
+
+ Australian Research Environment (ARE) +
+
+
\ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 01a5aee53..eaee2e427 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,6 @@ hide: - navigation - toc --- -

@@ -16,7 +15,7 @@ hide:
- +
New to ACCESS-Hive?
Get Started
@@ -75,4 +74,4 @@ hide: We at ACCESS-NRI acknowledge the Traditional Owners of the land on which our research infrastructure and community operate across Australia and pay our respects to Elders past and present. We recognise the thousands of years of accumulated knowledge and deep connection they have with all the Earth systems we simulate. - \ No newline at end of file + \ No newline at end of file diff --git a/docs/js/miscellaneous.js b/docs/js/miscellaneous.js index 1c1d6602f..4cba90061 100644 --- a/docs/js/miscellaneous.js +++ b/docs/js/miscellaneous.js @@ -21,17 +21,18 @@ function removeIconsFromHomepage() { partially covered by the sticky banner when clicking on a toc link */ function adjustScrollingToId() { - let header = document.querySelector('header'); - let links = document.querySelectorAll("a[href^='#'].md-nav__link,a[href^='#']:not([class])"); - - const clickEvent = e => { - e.preventDefault(); - window.scrollTo(0, document.querySelector(e.target.hash).offsetTop - header.offsetHeight); + function scrollToId() { + if (location.hash) { + let header = document.querySelector('header'); + let el = document.getElementById(location.hash.slice(1,)); + let offset = el.getBoundingClientRect().top - header.getBoundingClientRect().bottom; + if (offset != 0) { + window.scrollBy(0, offset); + } + } } - - links.forEach(link => { - link.addEventListener('click', clickEvent) - }) + document.querySelectorAll(`[href^="#"]`).forEach(el => el.addEventListener("click",(e) => setTimeout(scrollToId,0), false)); + scrollToId(); } @@ -39,38 +40,67 @@ function adjustScrollingToId() { Add functionality to tabs */ function tabFunctionality() { - // Make first tab and content active - document.querySelectorAll(".tabLabels :nth-child(1)").forEach(label=>label.classList.add("activeTab")); - document.querySelectorAll(".tabContents :nth-child(1)").forEach(content=>content.classList.add("activeTabContent")); + let activeEl = document.activeElement; + // If tab is activeElement (for example if a link points to an ID + // inside the tab content/button), make that tab active + if (activeEl.parentElement.classList.contains("tabLabels")) { + activeEl.blur(); + openTab(activeEl); + } else { + // Otherwise first check if a tab was open and a page reloaded, and open the same tab, + // otherwise open first tab + document.querySelectorAll(".tabLabels").forEach(tabs => { + let label = tabs.getAttribute("label"); + let index; + if (sessionStorage.getItem(`tabs-label=${label}`)) { + index = sessionStorage.getItem(`tabs-label=${label}`); + } else { + index = '1'; + } + // tabs.querySelector(`:nth-child(${index})`).classList.add("activeTab"); + // document.querySelectorAll(`.tabContents[label="${label}"] > :nth-child(${index})`).forEach(content => content.classList.add("activeTabContent")); + openTab(tabs.querySelector(`:nth-child(${index})`)); + }) + } // Add click event to tab buttons let tabButtons = document.querySelectorAll(".tabLabels > button"); tabButtons.forEach(button=>{ button.addEventListener('click', openTab); }) + + // Add click event for links to tab IDs on the same page + document.querySelectorAll('[href^="#"]:not([class^="md"])').forEach(el => { + let href = el.getAttribute('href'); + let tabEl = document.getElementById(href.slice(1,)) + if (tabEl.parentElement.classList.contains("tabLabels")) { + el.addEventListener("click",(e) => openTab(tabEl), false); + } + }) function openTab(e) { - let active = e.currentTarget; + let active; + if (e.currentTarget) { + active = e.currentTarget; + } else { + active = e; + } let label = active.parentElement.getAttribute('label'); let index = Array.from(active.parentElement.children).indexOf(active)+1; // Remove active classes from button/content - document.querySelectorAll(`.tabContents[label=${label}]`).forEach(tabContent => { - for (let content of tabContent.children) { - content.classList.remove('activeTabContent'); - } + document.querySelectorAll(`.tabContents[label=${label}] > .activeTabContent`).forEach(content => { + content.classList.remove('activeTabContent'); }) - document.querySelectorAll(`.tabLabels[label=${label}]`).forEach(tabLabel => { - for (let button of tabLabel.children) { - button.classList.remove('activeTab'); - } + document.querySelectorAll(`.tabLabels[label=${label}] > .activeTab`).forEach(button => { + button.classList.remove('activeTab'); }) // Add active classes to button/content and add focus - document.querySelectorAll(`.tabContents[label=${label}] :nth-child(${index})`).forEach(content => { - content.classList.add('activeTabContent') + document.querySelectorAll(`.tabContents[label=${label}] > :nth-child(${index})`).forEach(content => { + content.classList.add('activeTabContent'); }) - document.querySelectorAll(`.tabLabels[label=${label}] :nth-child(${index})`).forEach(label => { - label.classList.add('activeTab') + document.querySelectorAll(`.tabLabels[label=${label}] > :nth-child(${index})`).forEach(button => { + button.classList.add('activeTab'); }) - + sessionStorage.setItem(`tabs-label=${label}`,`${index}`); } } @@ -79,7 +109,7 @@ function tabFunctionality() { Add the external-link icon to
tags with target="_blank" */ function addExternalLinkIcon() { - let extLinks = document.querySelectorAll("article a[target='_blank']:not(:has(img))"); + let extLinks = document.querySelectorAll("article a[target='_blank']:not(:is(.vertical-card,.horizontal-card))"); extLinks.forEach(link => { link.classList.add('external-link'); }) @@ -89,6 +119,7 @@ function addExternalLinkIcon() { /* Add button to toggle terminal-animations for the whole page (next to the page title) */ +// Change it to be using "localStorage" once animated-terminal.js has been updated to set/remove "static" attribute dynamically. function toggleTerminalAnimations() { if (document.querySelector('terminal-window')) { let state; @@ -114,7 +145,7 @@ function toggleTerminalAnimations() { } function setCookie() { - document.cookie = `terminalState=${state};path=/;max-age=2592000;samesite=lax`; // Expires after 1 month + document.cookie = `terminalState=${state};path=/;max-age=604800;samesite=lax`; // Expires after 1 week } function toggleState(e) { @@ -136,22 +167,17 @@ function toggleTerminalAnimations() { } applyState(); let terminalAnimationsSwitch = document.createElement('img'); - let rootDir; - if (location.pathname.startsWith('/development_site')) { - rootDir = `${location.origin}/development_site`; - } else if (location.pathname.startsWith('/pr-preview')) { - rootDir = `${location.origin}${location.pathname.split('/').slice(0,3).join('/')}`; - } else { - rootDir = location.origin; - } - terminalAnimationsSwitch.setAttribute('src',`${rootDir}/assets/terminal_animation_switch_${state}.png`); + terminalAnimationsSwitch.setAttribute('src',`/assets/terminal_animation_switch_${state}.png`); let current = state == 'active' ? 'enabled' : 'disabled'; let onclick = state == 'active' ? 'disable' : 'enable'; terminalAnimationsSwitch.setAttribute('title',`Terminal animations ${current}.\nClick to ${onclick} them.`); terminalAnimationsSwitch.setAttribute('id','terminalSwitch'); - let h1 = document.querySelector('h1'); - h1.parentElement.insertBefore(terminalAnimationsSwitch, h1); - terminalAnimationsSwitch.addEventListener('click', toggleState, false); + document.querySelectorAll('h1').forEach(h1 => { + let _switch = terminalAnimationsSwitch.cloneNode(true); + _switch.addEventListener('click', toggleState, false); + h1.parentElement.insertBefore(_switch, h1); + }) + terminalAnimationsSwitch.remove(); } } @@ -186,18 +212,37 @@ function fitText() { }) } + +/* + Make footnote citations link to article +*/ +function makeCitationLinks() { + let match; + let href; + document.querySelectorAll('.footnote [id^="fn:"] > p').forEach(el => { + if (match = el.innerHTML.match('${el.innerHTML}`; + } else if (match = el.innerHTML.match('URL: ${el.innerHTML}`; + } + }) +} + + // Join all functions function main() { - sortTables(); - removeIconsFromHomepage(); adjustScrollingToId(); tabFunctionality(); + sortTables(); + removeIconsFromHomepage(); addExternalLinkIcon(); + fitText(); toggleTerminalAnimations(); + makeCitationLinks(); // addCardContainerChildrenNumber(); - fitText(); } // Run all functions -// window.onload = () => document$.subscribe(() => main()); -document$.subscribe(() => main()); \ No newline at end of file +window.onload = () => document$.subscribe(() => main()); \ No newline at end of file diff --git a/docs/model_evaluation/index.md b/docs/model_evaluation/index.md index a833ee52d..50a70228a 100644 --- a/docs/model_evaluation/index.md +++ b/docs/model_evaluation/index.md @@ -9,7 +9,7 @@ Model evaluation in climate science is the process of assessing the performance
- +
Computing Access
diff --git a/docs/model_evaluation/model_evaluation_getting_started/index.md b/docs/model_evaluation/model_evaluation_getting_started/index.md index 9be25276e..ff07c0ded 100644 --- a/docs/model_evaluation/model_evaluation_getting_started/index.md +++ b/docs/model_evaluation/model_evaluation_getting_started/index.md @@ -22,7 +22,7 @@ Model Evaluation and Diagnostics (MED) of ACCESS models includes: Here you can find information on how to access curated data stored at NCI and how to use it to evaluate specific models, such as comparing model output with observational data.
- +
Computing Access
diff --git a/docs/model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md b/docs/model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md index c223d3312..e57a57212 100644 --- a/docs/model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md +++ b/docs/model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md @@ -1,11 +1,11 @@ # `conda` Environment for Model Evaluation on Gadi -If you do not yet have `ssh` access to Gadi, refer to instructions on how to
login to Gadi. +If you do not yet have `ssh` access to Gadi, refer to instructions on how to login to Gadi. The following instructions explain how to load the curated `python` environment on NCI, which includes packages and scripts supported by ACCESS-NRI. Once loaded, these can be run directly on Gadi via `ssh`, `PBS` scripts, or in `JupyterLab`. ???+ warning "ACCESS-NRI can provide code and support, but not computing resources" - You do not automatically have access to all `/g/data/` storage on Gadi. You need to join an NCI project to view files on `/g/data/$PROJECT`. + You do not automatically have access to all `/g/data/` storage on Gadi. You need to join an NCI project to view files on `/g/data/$PROJECT`.
For model evaluation and diagnostics, you need to join projects `xp65` and `hh5` for code access and a `$PROJECT` with sufficient compute resources. @@ -98,10 +98,10 @@ For more information on running `PBS` jobs on NCI, refer to login to ARE, click on JupyterLab in the Featured Apps section to launch a `JupyterLab` instance.
diff --git a/docs/model_evaluation/model_evaluation_model_catalogs/model_evaluation_search_models.md b/docs/model_evaluation/model_evaluation_model_catalogs/model_evaluation_search_models.md index bed729fd1..d8d0775e2 100644 --- a/docs/model_evaluation/model_evaluation_model_catalogs/model_evaluation_search_models.md +++ b/docs/model_evaluation/model_evaluation_model_catalogs/model_evaluation_search_models.md @@ -2,7 +2,7 @@ To have the huge amount of data from different experiments on the NCI storage at the palm of your hand, we provide a ("meta") catalog for you to query via python as part of the `#!python intake` package with our curated catalog plugin `#!python intake.cat.access_nri` . -To use this catalog, you need access to NCI's Gadi. Check out our [Getting Started with ACCESS at NCI](../model_evaluation_getting_started/index.md) guide on how to get access. +To use this catalog, you need access to NCI's Gadi. Check out our [Getting Started with ACCESS at NCI](../model_evaluation_getting_started/first_steps.md) guide on how to get access. Once logged in to Gadi, you will need to add the `#!python access-nri-catalog` to your `#!python conda` environments and start an [ARE JupyterLab Session](https://are.nci.org.au/pun/sys/dashboard). Check out our [ACCESS-NRI Intake Catalog](https://github.com/ACCESS-NRI/access-nri-intake-catalog/blob/main/docs/getting_started/index.rst) guide for the specific setup (note that you can only read in data from specific experiments if they are loaded through the *Storage* keyword). diff --git a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md index dcf56fdb9..de389f61f 100644 --- a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md +++ b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md @@ -16,7 +16,7 @@ This documentation is tailored to using the tool within the NCI infrastructure a ## Using ILAMB and IOMB on Gadi -`ilamb` is provided through both the `xp65` and `hh5` code projects on Gadi at the National Computational Infrastructure. To use `ilamb` through this infrastructure, you need to have an NCI account and join the projects. See our [Getting Started Guide](../../getting_started/index.md). +`ilamb` is provided through both the `xp65` and `hh5` code projects on Gadi at the National Computational Infrastructure. To use `ilamb` through this infrastructure, you need to have an NCI account and join the projects. See our [Getting Started Guide](../../getting_started/first_steps.md). You will find the information needed to run ILAMB and IOMB on Gadi in our documentation: diff --git a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_pangeo_cosima.md b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_pangeo_cosima.md index 1748d3692..7ea31adbb 100644 --- a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_pangeo_cosima.md +++ b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_pangeo_cosima.md @@ -13,7 +13,7 @@ The COSIMA Cookbook is a framework for analysing output from ocean-sea ice model ## Getting Started -The easiest way to use the COSIMA Cookbook is through the Australian Research Environment (ARE) access of the National Computational Infrastructure. Here, we assume that you already [got started](../../../getting_started), that is, you have an NCI account and can log onto Gadi via secure shell (ssh). +The easiest way to use the COSIMA Cookbook is through the Australian Research Environment (ARE) access of the National Computational Infrastructure. Here, we assume that you already [got started](/getting_started/first_steps), that is, you have an NCI account and can log onto Gadi via secure shell (ssh). To use the COSIMA Cookbook that is preinstalled in the `conda/analysis3` of NCI proejct `hh5`, you need to join NCI project `hh5`. @@ -24,7 +24,7 @@ To use the COSIMA Cookbook that is preinstalled in the `conda/analysis3` of NCI **Module directories**: /g/data/hh5/public/modules **Modules**: conda/analysis3 You can check out our [Getting Started with ARE](../model_evaluation_getting_started/model_evaluation_getting_started.md) instructions if you have not used ARE before. -4. Within the ARE environment, navigate to one of the COSIMA recipes and run the analysis. +1. Within the ARE environment, navigate to one of the COSIMA recipes and run the analysis. ## More information about the Cookbook diff --git a/docs/models/configurations/access-am.md b/docs/models/configurations/access-am.md index 98509d32a..1f0cbaa75 100644 --- a/docs/models/configurations/access-am.md +++ b/docs/models/configurations/access-am.md @@ -17,7 +17,7 @@ The component models are the same as ACCESS-CM2: - Land surface model (CABLE2.5) -[**Citation** [@Bi2020-vj]][ACCESS-CM2-cite] +[**Citation** [@Bi2020]][ACCESS-CM2-cite] ### Other configurations diff --git a/docs/models/configurations/access-cm.md b/docs/models/configurations/access-cm.md index 0412c21fd..e49d79bc7 100644 --- a/docs/models/configurations/access-cm.md +++ b/docs/models/configurations/access-cm.md @@ -7,7 +7,7 @@ It produces physical climate simulations. ## ACCESS-CM2 -ACCESS-CM2 [@Bi2020-vj] was initially developed by CSIRO and is one of Australia’s contributions to the World Climate Research Programme’s Coupled Model Intercomparison Project Phase 6 (CMIP6). +ACCESS-CM2 [@Bi2020] was initially developed by CSIRO and is one of Australia’s contributions to the World Climate Research Programme’s Coupled Model Intercomparison Project Phase 6 (CMIP6). ### Model components - Atmoshpere: UM10.6, GA7.1 science configuration. N96 spatial resolution (1.875° x 1.25°), 85 vertical levels. Physical model only – no carbon cycle. @@ -18,7 +18,7 @@ It produces physical climate simulations. - Ocean: MOM5. Tripolar grid, 1° spatial resolution, 50 vertical levels. -- Sea ice: CICE5.1.2. Same grid as ocean. +- Sea ice: CICE5.1.2. Same grid as ocean. - Coupler: OASIS3-MCT. diff --git a/docs/models/configurations/access-esm.md b/docs/models/configurations/access-esm.md index 662a6afa6..52fa564f9 100644 --- a/docs/models/configurations/access-esm.md +++ b/docs/models/configurations/access-esm.md @@ -8,7 +8,7 @@ This means it can simulate both the physical climate and global biogeochemical c ## ACCESS-ESM1.5 -ACCESS-ESM1.5 [@Ziehn2020-fq] is a fully-coupled climate model with land and ocean carbon cycle components. ACCESS-ESM1.5 was developed primarily to enable Australia to participate in the Coupled Model Intercomparison Project Phase 6 (CMIP6) with an ESM version. +ACCESS-ESM1.5 [@Ziehn2020] is a fully-coupled climate model with land and ocean carbon cycle components. ACCESS-ESM1.5 was developed primarily to enable Australia to participate in the Coupled Model Intercomparison Project Phase 6 (CMIP6) with an ESM version. ### Model components @@ -22,7 +22,7 @@ This means it can simulate both the physical climate and global biogeochemical c - Ocean Biogeochemistry: WOMBAT. -- Sea ice: CICE5.1.2. Same grid as ocean. +- Sea ice: CICE5.1.2. Same grid as ocean. - Coupler: OASIS3-MCT. diff --git a/docs/models/configurations/access-om.md b/docs/models/configurations/access-om.md index 514be5ea9..91b18c263 100644 --- a/docs/models/configurations/access-om.md +++ b/docs/models/configurations/access-om.md @@ -9,7 +9,7 @@ The atmospheric fields that drive the model are provided by a data source, usual ## ACCESS-OM2 -ACCESS-OM2 [@Kiss2020-gmd] is a suite of coupled ocean-sea ice models developed by the Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA). +ACCESS-OM2 [@Kiss2020] is a suite of coupled ocean-sea ice models developed by the Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA). The ACCESS-OM2 has versions at three different spatial resolutions: ACCESS-OM2, ACCESS-OM2-025 and ACCESS-OM2-01. @@ -37,7 +37,7 @@ The ACCESS-OM2 has versions at three different spatial resolutions: Ocean Biogeochemistry: WOMBAT.
  • - Sea ice: CICE5.1.2. Same grid as ocean. + Sea ice: CICE5.1.2. Same grid as ocean.
  • Coupler: OASIS3-MCT. @@ -58,7 +58,7 @@ The ACCESS-OM2 has versions at three different spatial resolutions: Ocean Biogeochemistry: WOMBAT.
  • - Sea ice: CICE5.1.2. Same grid as ocean. + Sea ice: CICE5.1.2. Same grid as ocean.
  • Coupler: OASIS3-MCT. @@ -79,7 +79,7 @@ The ACCESS-OM2 has versions at three different spatial resolutions: Ocean Biogeochemistry: WOMBAT.
  • - Sea ice: CICE5.1.2. Same grid as ocean. + Sea ice: CICE5.1.2. Same grid as ocean.
  • Coupler: OASIS3-MCT. diff --git a/docs/models/configurations/index.md b/docs/models/configurations/index.md index b5b4b7897..1fbc6cd80 100644 --- a/docs/models/configurations/index.md +++ b/docs/models/configurations/index.md @@ -1,6 +1,6 @@ # Supported ACCESS Model Configurations -
    +
    diff --git a/docs/models/index.md b/docs/models/index.md index abf10f781..58ddcd285 100644 --- a/docs/models/index.md +++ b/docs/models/index.md @@ -9,7 +9,7 @@ ACCESS models are computer codes comprising complex mathematical representations ## Supported ACCESS Model Configurations -
    +
    diff --git a/docs/models/model_components/coupler.md b/docs/models/model_components/coupler.md index a613449f6..39324e731 100644 --- a/docs/models/model_components/coupler.md +++ b/docs/models/model_components/coupler.md @@ -15,5 +15,5 @@ OASIS3-MCT is the coupler used in National Unified Operational Prediction Capability (NUOPC) interoperability layer defines conventions and a set of generic components for building coupled models using the Earth System Modeling Framework (ESMF). -### Configurations that use OASIS3-MCT -OASIS3-MCT is not yet included in any ACCESS-NRI-supported configuration, but will be included in ACCESS-OM3, a configuration currently under development. \ No newline at end of file +### Configurations that use NUOPC +NUOPC is not yet included in any ACCESS-NRI-supported configuration, but will be included in ACCESS-OM3, a configuration currently under development. \ No newline at end of file diff --git a/docs/models/model_components/land.md b/docs/models/model_components/land.md index a7a3f5bdb..0b42ee4fe 100644 --- a/docs/models/model_components/land.md +++ b/docs/models/model_components/land.md @@ -1,4 +1,4 @@ -# Land component +# Land Surface component diff --git a/docs/models/model_components/ocean.md b/docs/models/model_components/ocean.md index 26702917f..4a1e3c35c 100644 --- a/docs/models/model_components/ocean.md +++ b/docs/models/model_components/ocean.md @@ -11,8 +11,8 @@ MOM is an open source development by a consortium of scientists across several g There are 2 MOM versions currently used in ACCESS models: MOM5 and MOM6.
    - - + +
    diff --git a/docs/models/model_components/sea-ice.md b/docs/models/model_components/sea-ice.md index 7543401f8..9c31148a2 100644 --- a/docs/models/model_components/sea-ice.md +++ b/docs/models/model_components/sea-ice.md @@ -9,8 +9,8 @@ CICE is a numerical model for simulating the growth, melting and movement of pol There are 2 CICE versions currently used in ACCESS models: CICE5 and CICE6.
    - - + +
    diff --git a/docs/models/run-a-model/index.md b/docs/models/run-a-model/index.md index 1816d81e1..45a9b0ffd 100644 --- a/docs/models/run-a-model/index.md +++ b/docs/models/run-a-model/index.md @@ -1,5 +1,5 @@ # Run a Model -If you are a new user of ACCESS climate models, please refer to the [Getting Started](../../../getting_started) section. +If you are a new user of ACCESS climate models, please refer to the [First Steps](/getting_started/first_steps) section. If you are unsure which ACCESS model is the right choice for your experiment, take a look at the overview of [ACCESS Models](../). diff --git a/docs/models/run-a-model/run-access-cm.md b/docs/models/run-a-model/run-access-cm.md index 47770857e..34875f572 100644 --- a/docs/models/run-a-model/run-access-cm.md +++ b/docs/models/run-a-model/run-access-cm.md @@ -1,13 +1,40 @@ {% set model = "ACCESS-CM" %} -# Run {{ model }} -## Requirements -### General requirements -Before running {{ model }}, you need to fulfil general requirements outlined in the [Getting Started](../../../getting_started) section. + +
    + + +
    + +
    + +
    +

    Run {{ model }} from ARE / Gadi

    +
    + +
    +

    Run {{ model }} from accessdev

    +
    +
    + + +
    + The workflow to run ACCESS_CM is currently in transition from accessdev to ARE/Gadi. +
    + The tabs above let you choose the type of workflow you would like to follow. +
    +
    + If you are new to ACCESS-CM, we strongly suggest you follow the ARE/Gadi workflow, as the accessdev workflow will soon be interrupted. +
    -### Model-specific requirements +## Prerequisites + +### General prerequisites +Before running {{ model }}, you need to fulfil general prerequisites outlined in the [First Steps](/getting_started/first_steps) section. + +### Model-specific prerequisites
    • - Get a MOSRS account + MOSRS account
      The Met Office Science Repository Service (MOSRS) is a server run by the UK Met Office (UKMO) to support collaborative development with other partners organisations. MOSRS contains the source code and configurations for some model components in {{ model }} (e.g., the UM).
      @@ -22,81 +49,264 @@ Before running {{ model }}, you need to fulfil general requirements outlined in
    For more information on how to join specific NCI projects, please refer to How to connect to a project.
  • -
  • - Connect to accessdev + +
    + +
    +
  • + Connection to an ARE VDI Desktop +
    + To run {{ model }}, you need to be able to start an Australian Research Environment (ARE) VDI Desktop session. +
    + If u are not familiar with ARE, please check the Getting Started on ARE section. +
  • +
    + +
    +
  • + Connection to accessdev +
    + To run {{ model }}, you need to be able to connect to accessdev. This is an NCI server providing configuration and run control for {{ model }}. +
    + You also need to ensure there is correct communication between accessdev and Gadi. +
    + To complete these steps, refer to the SSH & SSH Agent section in the Getting Connected to Accessdev guide. +
  • +
    +
    + + + +-------------------------------------------- +## Setup for your chosen workflow +
    + +
    +
    + Your chosen workflow is ARE / Gadi. If you want to run {{ model }} on accessdev instead, please select accessdev workflow. +
    +

    Launch ARE VDI Session

    + Go to the ARE VDI page and launch a session with the following directives: +
      +
    • + Walltime (hours) → ≈ 4 per simulated year +
      + With the current state of the ARE/Gadi workflow, the ARE VDI session needs to remain active and running for the entirety of the {{ model }} simulation. If the ARE VDI session expires before the end of the simulation, the simulation itself will be terminated as well. +
      +
      + This means that walltime needs to be set according to the simulation length. +
      + A good estimate to calculate the walltime needed is 4 hours per simulated year. +
      + ARE VDI Session cannot be spun up for more than 48 consecutive hours. This means that {{ model }} simulations that need more than 48 hours to complete, at the current state, need to be broken down into multiple chunks running for up to 48 hours. +
      +
      + In the near future this will not be necessary anymore, as there will be long running servers in place for runnning {{ model }} simulations. +
      +
    • +
    • + Queuenormalbw +
    • +
    • + Compute Sizetiny (1 CPU) +
      + {{ model }} runs on a different Gadi node with respect to the one where the ARE VDI session is launched. +
      + This means that the ARE VDI session only needs to carry out setup steps as well as starting the run itself. All these tasks can be easily done with only 1 CPU. +
    • +
    • + Project → a project you belong, with allocated SU +
      + The project, with allocated Service Units (SU), under which you want to run your simulation. Usually (but not always) this corresponds to your $PROJECT. +
      + For more information, check how to join relevant NCI projects. +
    • +
    • + Storagegdata/access+gdata/hh5+gdata/hr22+gdata/ki32 (minimum) +
      + This is the list (joined by + signs) of project data storage needed for the {{ model }} simulation. In ARE, storage locations need to be explicitly defined to access data from within a VDI instance. +
      + Since every {{ model }} simulation can be unique and input data can come from various sources, if your specific simulation requires data coming from projects other than access, hh5, hr22 or ki32, you need to add those projects to the storage path. +
      + For example, if your {{ model }} simulation requires data coming from /g/data/tm70 and /scratch/w40, your full storage path will be: gdata/access+gdata/hh5+gdata/hr22+gdata/ki32+/gdata/tm70+scratch/w40 +
    • +
    + Launch the session and, after the session starts, click on Launch VDI Desktop. + Launch ARE VDI session
    - To run {{ model }}, you need to connect to accessdev. This is an NCI server providing configuration and run control for {{ model }}. +

    Open the terminal

    + After the new tab opens you will see a Desktop with a few folders on the left.
    - You also need to ensure there is correct communication between accessdev and Gadi. + To open the terminal click on the black terminal icon at the top of the window.
    - To complete these steps, refer to the SSH & SSH Agent section in the Getting Connected to Accessdev guide. - - + As you can see from your terminal, you are now connected to a Gadi computing node. + Open ARE VDI terminal +
    + +
    +
    + Your chosen workflow is accessdev. If you want to run {{ model }} on ARE / Gadi instead, please select ARE / Gadi workflow. +
    + Login to accessdev by runnning: +
    ssh accessdev
    +
    + If you have not yet set up your accessdev connection through `ssh`, please check the Getting Connected to Accessdev guide. +
    +
    +
    + --------------------------------------------- ## Get {{ model }} suite {{ model }} comprises the model components UM, MOM, CICE, CABLE and OASIS. These components, which have different model parameters, input data and computer-related information, need to be packaged together as a suite in order to run.
    -Each {{ model }} suite has an ID in the format u-<suite-name>, where <suite-name> is a unique identifier. For example, u-br565 is the CMIP6-release preindustrial experiment suite. +Each {{ model }} suite has a suite-ID in the format u-<suite-name>, where <suite-name> is a unique identifier.
    -Typically, an existing suite is copied and then edited as needed for a particular run. +
    + +
    + For this example you can use u-cy339, which is a preindustrial experiment suite. +
    + Typically, an existing suite is copied and then edited as needed for a particular run. +
    + +
    + For this example you can use u-br565, which is the CMIP6-release preindustrial experiment suite. +
    + Typically, an existing suite is copied and then edited as needed for a particular run. +
    +
    + ### Copy {{ model }} suite with Rosie Rosie is an SVN repository wrapper with a set of options specific for {{ model }} suites.
    -
    -To copy an existing suite on accessdev you need to follow two main steps: -
      -
    1. - MOSRS authentication -
      - To authenticate using your MOSRS credentials, run: -
      mosrs-auth
      - - mosrs-auth - Please enter the MOSRS password for <MOSRS-username>: - Successfully authenticated with MOSRS as <MOSRS-username> - -
    2. -
    3. - Copy a suite -
      -
        + +
        + +
        + To copy an existing suite on Gadi you need to follow three main steps: +
        1. - Local-only copy + Get Cylc7 setup
          - To create a local copy of the <suite-ID> from the UKMO repository, run: -
          rosie checkout <suite-ID>
          + To get the Cylc7 setup required to run {{ model }}, execute the following commands: +
          module use /g/data/hr22/modulefiles
          +module load cylc7
          + + module use /g/data/hr22/modulefiles + module load cylc7 + Loading cylc7/23.03 +  Loading requirement: mosrs-setup/1.0.1 + +
        2. +
        3. + MOSRS authentication +
          + To authenticate using your MOSRS credentials, run: +
          mosrs-auth
          - rosie checkout <suite-ID> - [INFO] create: /home/565/<$USER>/roses - [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<suite-ID> + mosrs-auth + INFO: You need to enter your MOSRS credentials here so that GPG can cache your password. + Please enter the MOSRS password for <MOSRS-username>: + INFO: Checking your credentials using Subversion. Please wait. + INFO: Successfully accessed Subversion with your credentials. + INFO: Checking your credentials using rosie. Please wait. + INFO: Successfully accessed rosie with your credentials. - This option is mostly used for testing and examining existing suites.
        4. - Remote and local copy -
          - Alternatively, to create a new copy of an existing <suite-ID> both locally and remotely in the UKMO repository, run: -
          rosie copy <suite-ID>
          + Copy a suite +
          +
            +
          • + Local-only copy +
            + To create a local copy of the <suite-ID> from the UKMO repository, run: +
            rosie checkout <suite-ID>
            + + rosie checkout <suite-ID> + [INFO] create: /home/565/<$USER>/roses + [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<suite-ID> + + This option is mostly used for testing and examining existing suites. +
          • +
          • + Remote and local copy +
            + Alternatively, to create a new copy of an existing <suite-ID> both locally and remotely in the UKMO repository, run: +
            rosie copy <suite-ID>
            + + rosie copy <suite-ID> + Copy "<suite-ID>/trunk@<trunk-ID>" to "u-?????"? [y or n (default)] y + [INFO] <new-suite-ID>: created at https://code.metoffice.gov.uk/svn/roses-u/<suite-n/a/m/e/> + [INFO] <new-suite-ID>: copied items from <suite-ID>/trunk@<trunk-ID> + [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<new-suite-ID> + + When a new suite is created in this way, a unique <suite-ID> is generated within the repository and populated with descriptive information about the suite and its initial configuration. +
          • +
          +
        5. +
        + For additional rosie options, run: +
        rosie help
        +
        + Suites are created in the user's home directory on Gadi under ~/roses/<suite-ID>. +
        + +
        + To copy an existing suite on accessdev you need to follow two main steps: +
          +
        1. + MOSRS authentication +
          + To authenticate using your MOSRS credentials, run: +
          mosrs-auth
          - rosie copy <suite-ID> - Copy "<suite-ID>/trunk@<trunk-ID>" to "u-?????"? [y or n (default)] y - [INFO] <new-suite-ID>: created at https://code.metoffice.gov.uk/svn/roses-u/<suite-n/a/m/e/> - [INFO] <new-suite-ID>: copied items from <suite-ID>/trunk@<trunk-ID> - [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<new-suite-ID> + mosrs-auth + Please enter the MOSRS password for <MOSRS-username>: + Successfully authenticated with MOSRS as <MOSRS-username> - When a new suite is created in this way, a unique <suite-ID> is generated within the repository and populated with descriptive information about the suite and its initial configuration.
        2. -
      -
    4. -
    - -For additional rosie options, run: -
    rosie help
    -
    -Suites are created in the user's home directory on accessdev under ~/roses/<suite-ID>. -
    +
  • + Copy a suite +
    +
      +
    • + Local-only copy +
      + To create a local copy of the <suite-ID> from the UKMO repository, run: +
      rosie checkout <suite-ID>
      + + rosie checkout <suite-ID> + [INFO] create: /home/565/<$USER>/roses + [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<suite-ID> + + This option is mostly used for testing and examining existing suites. +
    • +
    • + Remote and local copy +
      + Alternatively, to create a new copy of an existing <suite-ID> both locally and remotely in the UKMO repository, run: +
      rosie copy <suite-ID>
      + + rosie copy <suite-ID> + Copy "<suite-ID>/trunk@<trunk-ID>" to "u-?????"? [y or n (default)] y + [INFO] <new-suite-ID>: created at https://code.metoffice.gov.uk/svn/roses-u/<suite-n/a/m/e/> + [INFO] <new-suite-ID>: copied items from <suite-ID>/trunk@<trunk-ID> + [INFO] <suite-ID>: local copy created at /home/565/<$USER>/roses/<new-suite-ID> + + When a new suite is created in this way, a unique <suite-ID> is generated within the repository and populated with descriptive information about the suite and its initial configuration. +
    • +
    +
  • + + For additional rosie options, run: +
    rosie help
    +
    + Suites are created in the user's home directory on accessdev under ~/roses/<suite-ID>. +
    +
    + Each suite directory usually contains two subdirectories and three files:
    You are done!!

    @@ -261,7 +563,17 @@ To investigate the cause of a failure, we need to look at the logs job.err
    To access a specific task, click on the arrow next to the task to extend the drop-down menu with all the subtasks.
    - Investigate Error GUI +
    + +
    + Investigate Error GUI +
    + +
    + Investigate Error GUI +
    +
    +
  • Through the suite directory @@ -314,13 +626,29 @@ To scan for active suites, run:
    cylc scan
    To reopen the Cylc GUI, run the following command from within the suite directory:
    rose suite-gcontrol
    - - cylc scan - <suite-ID> <$USER>@accessdev.nci.org.au:<port> - cd ~/roses/<suite-ID> - rose suite-gcontrol - Cylc GUI - +
    + +
    + + cylc scan + <suite-ID> <$USER>@<gadi-cpu>.nci.org.au:<port> + cd ~/roses/<suite-ID> + rose suite-gcontrol + Cylc GUI + +
    + +
    + + cylc scan + <suite-ID> <$USER>@accessdev.nci.org.au:<port> + cd ~/roses/<suite-ID> + rose suite-gcontrol + Cylc GUI + +
    +
    + ### STOP a suite To shutdown a suite in a safe manner, run the following command from within the suite directory: @@ -348,39 +676,81 @@ There are two main ways to restart a suite:
    You may need to manually trigger failed tasks from the Cylc GUI.
    - - cylc - cd ~/roses/<suite-ID> - rose suite-run --restart - [INFO] export CYLC_VERSION=7.8.3 - [INFO] export ROSE_ORIG_HOST=accessdev.nci.org.au - [INFO] export ROSE_SITE= - [INFO] export ROSE_VERSION=2019.01.2 - [INFO] delete: log/rose-suite-run.conf - [INFO] symlink: rose-conf/<timestamp>-restart.conf <= log/rose-suite-run.conf - [INFO] delete: log/rose-suite-run.version - [INFO] symlink: rose-conf/<timestamp>-restart.version <= log/rose-suite-run.version - [INFO] chdir: log/ - [INFO]         ._. - [INFO]         | |         The Cylc Suite Engine [7.8.3] - [INFO] ._____._. ._| |_____.      Copyright (C) 2008-2019 NIWA - [INFO] | .___| | | | | .___| & British Crown (Met Office) & Contributors. - [INFO] | !___| !_! | | !___. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ - [INFO] !_____!___. |_!_____! This program comes with ABSOLUTELY NO WARRANTY; - [INFO]     .___! |      see `cylc warranty`.  It is free software, you - [INFO]     !_____!       are welcome to redistribute it under certain - [INFO] - [INFO] *** listening on https://accessdev.nci.org.au:<port>/ *** - [INFO] - [INFO] To view suite server program contact information: - [INFO] $ cylc get-suite-contact <suite-ID> - [INFO] - [INFO] Other ways to see if the suite is still running: - [INFO] $ cylc scan -n '<suite-ID>' accessdev.nci.org.au - [INFO] $ cylc ping -v --host=accessdev.nci.org.au <suite-ID> - [INFO] $ ps -opid,args <PID> # on accessdev.nci.org.au - Cylc GUI - +
    + +
    + + cylc + cd ~/roses/<suite-ID> + rose suite-run --restart + [INFO] export CYLC_VERSION=7.9.7 + [INFO] export ROSE_ORIG_HOST=<gadi-cpu>.nci.org.au + [INFO] export ROSE_SITE=nci + [INFO] export ROSE_VERSION=2019.01.2 + [INFO] delete: log/rose-suite-run.conf + [INFO] symlink: rose-conf/<timestamp>-restart.conf <= log/rose-suite-run.conf + [INFO] delete: log/rose-suite-run.version + [INFO] symlink: rose-conf/<timestamp>-restart.version <= log/rose-suite-run.version + [INFO] chdir: log/ + [INFO]         ._. + [INFO]         | |         The Cylc Suite Engine [7.9.7] + [INFO] ._____._. ._| |_____.      Copyright (C) 2008-2019 NIWA + [INFO] | .___| | | | | .___| & British Crown (Met Office) & Contributors. + [INFO] | !___| !_! | | !___. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + [INFO] !_____!___. |_!_____! This program comes with ABSOLUTELY NO WARRANTY; + [INFO]     .___! |      see `cylc warranty`.  It is free software, you + [INFO]     !_____!       are welcome to redistribute it under certain + [INFO] + [INFO] *** listening on https://<gadi-cpu>.nci.org.au:<port>/ *** + [INFO] + [INFO] To view suite server program contact information: + [INFO] $ cylc get-suite-contact <suite-ID> + [INFO] + [INFO] Other ways to see if the suite is still running: + [INFO] $ cylc scan -n '<suite-ID>' <gadi-cpu>.nci.org.au + [INFO] $ cylc ping -v --host=<gadi-cpu>.nci.org.au <suite-ID> + [INFO] $ ps -opid,args <PID> # on <gadi-cpu>.nci.org.au + Cylc GUI + +
    + +
    + + cylc + cd ~/roses/<suite-ID> + rose suite-run --restart + [INFO] export CYLC_VERSION=7.8.3 + [INFO] export ROSE_ORIG_HOST=accessdev.nci.org.au + [INFO] export ROSE_SITE= + [INFO] export ROSE_VERSION=2019.01.2 + [INFO] delete: log/rose-suite-run.conf + [INFO] symlink: rose-conf/<timestamp>-restart.conf <= log/rose-suite-run.conf + [INFO] delete: log/rose-suite-run.version + [INFO] symlink: rose-conf/<timestamp>-restart.version <= log/rose-suite-run.version + [INFO] chdir: log/ + [INFO]         ._. + [INFO]         | |         The Cylc Suite Engine [7.8.3] + [INFO] ._____._. ._| |_____.      Copyright (C) 2008-2019 NIWA + [INFO] | .___| | | | | .___| & British Crown (Met Office) & Contributors. + [INFO] | !___| !_! | | !___. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + [INFO] !_____!___. |_!_____! This program comes with ABSOLUTELY NO WARRANTY; + [INFO]     .___! |      see `cylc warranty`.  It is free software, you + [INFO]     !_____!       are welcome to redistribute it under certain + [INFO] + [INFO] *** listening on https://accessdev.nci.org.au:<port>/ *** + [INFO] + [INFO] To view suite server program contact information: + [INFO] $ cylc get-suite-contact <suite-ID> + [INFO] + [INFO] Other ways to see if the suite is still running: + [INFO] $ cylc scan -n '<suite-ID>' accessdev.nci.org.au + [INFO] $ cylc ping -v --host=accessdev.nci.org.au <suite-ID> + [INFO] $ ps -opid,args <PID> # on accessdev.nci.org.au + Cylc GUI + +
    +
    +

  • @@ -433,31 +803,61 @@ This directory contains two subdirectories: For the atmospheric output data, the files are typically a UM fieldsfile or netCDF file, formatted as <suite-name>a.p<output-stream-identifier><year><month-string>.
    -For the u-br565 suite in this example, the atm directory contains: - - cd /scratch/<$PROJECT>/<$USER>/archive - ls - br565 <other-suite-name> <other-suite-name> - cd br565 - ls - history restart - ls history/atm - br565a.pd0950apr.nc br565a.pd0950aug.nc br565a.pd0950dec.nc br565a.pd0950feb.nc br565a.pd0950jan.nc br565a.pd0950jul.nc br565a.pd0950jun.nc br565a.pd0950mar.nc br565a.pd0950may.nc br565a.pd0950nov.nc br565a.pd0950oct.nc br565a.pd0950sep.nc br565a.pd0951apr.nc br565a.pd0951aug.nc br565a.pd0951dec.nc br565a.pm0950apr.nc br565a.pm0950aug.nc br565a.pm0950dec.nc br565a.pm0950feb.nc br565a.pm0950jan.nc br565a.pm0950jul.nc br565a.pm0950jun.nc br565a.pm0950mar.nc br565a.pm0950may.nc br565a.pm0950nov.nc br565a.pm0950oct.nc br565a.pm0950sep.nc br565a.pm0951apr.nc br565a.pm0951aug.nc br565a.pm0951dec.nc netCDF - - +
    + +
    + For the u-cy339 suite in this example, the atm directory contains: + + cd /scratch/<$PROJECT>/<$USER>/archive + ls + cy339 <other-suite-name> <other-suite-name> + cd cy339 + ls + history restart + ls history/atm + cy339a.pd0950apr.nc cy339a.pd0950aug.nc cy339a.pd0950dec.nc cy339a.pd0950feb.nc cy339a.pd0950jan.nc cy339a.pd0950jul.nc cy339a.pd0950jun.nc cy339a.pd0950mar.nc cy339a.pd0950may.nc cy339a.pd0950nov.nc cy339a.pd0950oct.nc cy339a.pd0950sep.nc cy339a.pd0951apr.nc cy339a.pd0951aug.nc cy339a.pd0951dec.nc cy339a.pm0950apr.nc cy339a.pm0950aug.nc cy339a.pm0950dec.nc cy339a.pm0950feb.nc cy339a.pm0950jan.nc cy339a.pm0950jul.nc cy339a.pm0950jun.nc cy339a.pm0950mar.nc cy339a.pm0950may.nc cy339a.pm0950nov.nc cy339a.pm0950oct.nc cy339a.pm0950sep.nc cy339a.pm0951apr.nc cy339a.pm0951aug.nc cy339a.pm0951dec.nc netCDF + +
    + +
    + For the u-br565 suite in this example, the atm directory contains: + + cd /scratch/<$PROJECT>/<$USER>/archive + ls + br565 <other-suite-name> <other-suite-name> + cd br565 + ls + history restart + ls history/atm + br565a.pd0950apr.nc br565a.pd0950aug.nc br565a.pd0950dec.nc br565a.pd0950feb.nc br565a.pd0950jan.nc br565a.pd0950jul.nc br565a.pd0950jun.nc br565a.pd0950mar.nc br565a.pd0950may.nc br565a.pd0950nov.nc br565a.pd0950oct.nc br565a.pd0950sep.nc br565a.pd0951apr.nc br565a.pd0951aug.nc br565a.pd0951dec.nc br565a.pm0950apr.nc br565a.pm0950aug.nc br565a.pm0950dec.nc br565a.pm0950feb.nc br565a.pm0950jan.nc br565a.pm0950jul.nc br565a.pm0950jun.nc br565a.pm0950mar.nc br565a.pm0950may.nc br565a.pm0950nov.nc br565a.pm0950oct.nc br565a.pm0950sep.nc br565a.pm0951apr.nc br565a.pm0951aug.nc br565a.pm0951dec.nc netCDF + +
    +
    + ### Restart files The restart files can be found in the /scratch/$PROJECT/$USER/archive/<suite-name>/restart directory, where they are categorised according to model components (similar to the history folder above).
    -The atmospheric restart files, which are UM fieldsfiles, are formatted as <suite-name>a.da<year><month><day>_00. - -For the u-br565 suite in this example, the atm directory contains: - - ls /scratch/<$PROJECT>/<$USER>/archive/br565/restart/atm - br565a.da09500201_00 br565a.da09510101_00 br565.xhist-09500131 br565.xhist-09501231 - +The atmospheric restart files, which are UM fieldsfiles, are formatted as <suite-name>a.da<year><month><day>_00. +
    + +
    + For the u-cy339 suite in this example, the atm directory contains: + + ls /scratch/<$PROJECT>/<$USER>/archive/cy339/restart/atm + cy339a.da09500201_00 cy339a.da09510101_00 cy339.xhist-09500131 cy339.xhist-09501231 + +
    + +
    + For the u-br565 suite in this example, the atm directory contains: + + ls /scratch/<$PROJECT>/<$USER>/archive/br565/restart/atm + br565a.da09500201_00 br565a.da09510101_00 br565.xhist-09500131 br565.xhist-09501231 + +
    +
    + Files formatted as <suite-name>a.xhist-<year><month><day> contain metadata information.
    @@ -475,4 +875,7 @@ Files formatted as <suite-name>a.xhist-<year><month><
  • https://code.metoffice.gov.uk/doc/um/latest/um-training/rose-gui.html
  • +
  • + https://opus.nci.org.au/display/DAE/Cylc+7+on+ARE +
  • \ No newline at end of file diff --git a/docs/models/run-a-model/run-access-esm.md b/docs/models/run-a-model/run-access-esm.md index c603d6ede..b5bd2f8d5 100644 --- a/docs/models/run-a-model/run-access-esm.md +++ b/docs/models/run-a-model/run-access-esm.md @@ -1,10 +1,10 @@ {% set model = "ACCESS-ESM" %} # Run {{ model }} -## Requirements -### General requirements -Before running {{ model }}, you need to fulfil general requirements outlined in the [Getting Started](../../../getting_started) section. +## Prerequisites +### General prerequisites +Before running {{ model }}, you need to fulfil general prerequisites outlined in the [First Steps](/getting_started/first_steps) section. -### Model-specific requirements +### Model-specific prerequisites