From 11949a1db61461c9a11320841266308072130d47 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Thu, 28 Aug 2025 15:54:42 +0200 Subject: [PATCH 1/4] surf setup as markdown --- docs/user-guide/tutorials/index.md | 2 +- .../tutorials/surf_research_cloud_setup.ipynb | 108 ------------------ .../tutorials/surf_research_cloud_setup.md | 84 ++++++++++++++ 3 files changed, 85 insertions(+), 109 deletions(-) delete mode 100644 docs/user-guide/tutorials/surf_research_cloud_setup.ipynb create mode 100644 docs/user-guide/tutorials/surf_research_cloud_setup.md diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index 339974ff..9bda40cf 100644 --- a/docs/user-guide/tutorials/index.md +++ b/docs/user-guide/tutorials/index.md @@ -5,7 +5,7 @@ maxdepth: 1 caption: Tutorials --- -surf_research_cloud_setup.ipynb +surf_research_cloud_setup.md ADCP_data_tutorial.ipynb CTD_data_tutorial.ipynb Drifter_data_tutorial.ipynb diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb deleted file mode 100644 index 299d9cb0..00000000 --- a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb +++ /dev/null @@ -1,108 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "vscode": { - "languageId": "plaintext" - } - }, - "source": [ - "# SURF Resarch Cloud: Virtualship environment setup\n", - "\n", - "> Note: \n", - "> This guide is specific to students who are enrolled at UU in the Dynamical Oceanography course.\n", - "\n", - "In the class, we use virtualship in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:\n", - "\n", - "- You aren't limited to the power of your laptop\n", - "- Input datasets are downloaded faster, as they're downloaded to the cloud instance (and not to your laptop)\n", - "\n", - "\n", - "## 1. Accepting SURF RC invite\n", - "\n", - "In your student email you'll have an invite from SURF Research Access Management (SRAM) to join a project on SURF RC. Accept this invite.\n", - "\n", - "## 2. Open the environment\n", - "\n", - "Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click \"access\" on the shared workspace.\n", - "\n", - "## 3. Jupyter workspace layout and additional config\n", - "\n", - "> Note: This only needs to be done once during setup.\n", - "\n", - "In the Jupyter workspace, you'll see the following in your file explorer:\n", - "```\n", - ".\n", - "├── KERNEL-README.ipynb\n", - "├── data\n", - "│ └── datasets\n", - "| └── shared-storage <--- The shared persistent storage\n", - "└── scratch\n", - "```\n", - "\n", - "The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., `mkdir data/shared-storage/{your-group-name}` replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n", - "\n", - "---\n", - "\n", - "To be able to run virtualship from the terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb` contains important information for configuring your environment. Namely, for our uses, the \"Initialize conda\" section. Do the following.\n", - "\n", - "> #### Initialize conda\n", - "> \n", - "> To make the already installed conda-tool available for yourself, you have to initialize your terminal shell.\n", - "> \n", - "> Start a \"Terminal\" tab in the Jupyter Lab launcher and type:\n", - "> ```\n", - "> /etc/miniconda/bin/conda init\n", - "> ```\n", - "> Close the terminal tab and start a new one.\n", - "> You will see that the terminal prompt has changed to something like\n", - "> ```\n", - "> (base) metheuser@mywsp:\n", - "> ```\n", - "> This is conda telling you that you are currently in the \"base\" environment.\n", - "\n", - "From here, you already have another environment set up for you. Running `conda env list` in the terminal, you should see:\n", - "\n", - "```bash\n", - "conda env list\n", - "\n", - "# conda environments:\n", - "#\n", - "base * /etc/miniconda\n", - "virtualship /etc/miniconda/envs/virtualship`\n", - "```\n", - "\n", - "Here you can do `conda activate virtualship` to activate the environment called \"virtualship\". This environment is a shared environment among all workspace users that can be centrally updated. If you want you can create and manage your own environments by running the relevant conda commands.\n", - "\n", - "With the `virtualship` environment, you now have access to the `virtualship` command in your terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-name}` and run `virtualship` commands as you would on your local machine.\n", - "\n", - "---\n", - "Finally, when you're working in Jupyter Notebooks, you are able to access the Conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI.\n", - "\n", - "\n", - "\n", - "## Course facilitator notes\n", - "\n", - "If `virtualship` is updated on GitHub, and you want to update the shared environment, you can do so by running the following commands in the terminal:\n", - "\n", - "```bash\n", - "conda activate virtualship\n", - "sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [] - } - ], - "metadata": { - "language_info": { - "name": "python" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.md b/docs/user-guide/tutorials/surf_research_cloud_setup.md new file mode 100644 index 00000000..5b191052 --- /dev/null +++ b/docs/user-guide/tutorials/surf_research_cloud_setup.md @@ -0,0 +1,84 @@ +# SURF Resarch Cloud: VirtualShip environment setup + +```{note} +This guide is specific to students who are enrolled at Utrecht University. +``` + +In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages: + +- You aren't limited to the power of your laptop +- Input datasets are downloaded faster, as they're downloaded to the cloud instance (and not to your laptop) + +## 1. Accepting SURF RC invite + +In your student email you'll have an invite from SURF Research Access Management (SRAM) to join a project on SURF RC. Accept this invite. + +## 2. Open the environment + +Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click "access" on the shared workspace. + +## 3. Jupyter workspace layout and additional config + +```{note} +This only needs to be done once during setup. +``` + +In the Jupyter workspace, you'll see the following in your file explorer: + +``` +. +├── KERNEL-README.ipynb +├── data +│ └── datasets +| └── shared-storage <--- The shared persistent storage +└── scratch +``` + +The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., `mkdir data/shared-storage/{your-group-name}` replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit. + +--- + +To be able to run VirtualShip from the Terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb`. This contains important information for configuring your environment. Namely, for our uses, the "Initialize conda" section. Do the following: + +#### Initialize conda + +To make the already installed conda-tool available for yourself, you have to initialize your Terminal shell. + +Start a "Terminal" tab in the Jupyter Lab launcher and type: `/etc/miniconda/bin/conda init` + +Close the Terminal tab and start a new one. +You will see that the Terminal prompt has changed to something like + +``` +(base) metheuser@mywsp: +``` + +This is conda telling you that you are currently in the "base" environment. + +From here, you already have another environment set up for you. Running `conda env list` in the Terminal, you should see: + +```bash +conda env list + +# conda environments: +# +base * /etc/miniconda +virtualship /etc/miniconda/envs/virtualship` +``` + +Here you can do `conda activate virtualship` to activate the environment called "virtualship". This environment is a shared environment among all workspace users that can be centrally updated. If you want, you can create and manage your own environments by running the relevant conda commands. + +With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-name}` and run `virtualship` commands as you would on your local machine. + +--- + +Finally, when you're working in Jupyter Notebooks, you are able to access the Conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI. + +## Course facilitator notes + +If `virtualship` is updated on GitHub, and you want to update the shared environment, you can do so by running the following commands in the Terminal: + +```bash +conda activate virtualship +sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main +``` From 087f1f97b62c71c6fa2cfed29400d49f21f888b1 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Thu, 28 Aug 2025 16:07:59 +0200 Subject: [PATCH 2/4] update surf environment dependencies --- docs/classroom-surf-environment.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/classroom-surf-environment.yml b/docs/classroom-surf-environment.yml index 4feda79a..51f33f18 100644 --- a/docs/classroom-surf-environment.yml +++ b/docs/classroom-surf-environment.yml @@ -45,8 +45,11 @@ miniconda: - opensimplex ==0.4.5 - numpy >=1,<2 - pydantic >=2,<3 - - copernicusmarine >=2 + - pyyaml + - copernicusmarine >= 2.2.2 - openpyxl + - yaspin + - textual # extra - xarray From 8ee20a49b388b7f1f569e747b69e1498fc349cfe Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Thu, 28 Aug 2025 16:29:58 +0200 Subject: [PATCH 3/4] revert tutorial to .ipynb --- docs/user-guide/tutorials/index.md | 2 +- .../tutorials/surf_research_cloud_setup.ipynb | 104 ++++++++++++++++++ .../tutorials/surf_research_cloud_setup.md | 84 -------------- 3 files changed, 105 insertions(+), 85 deletions(-) create mode 100644 docs/user-guide/tutorials/surf_research_cloud_setup.ipynb delete mode 100644 docs/user-guide/tutorials/surf_research_cloud_setup.md diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index 9bda40cf..339974ff 100644 --- a/docs/user-guide/tutorials/index.md +++ b/docs/user-guide/tutorials/index.md @@ -5,7 +5,7 @@ maxdepth: 1 caption: Tutorials --- -surf_research_cloud_setup.md +surf_research_cloud_setup.ipynb ADCP_data_tutorial.ipynb CTD_data_tutorial.ipynb Drifter_data_tutorial.ipynb diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb new file mode 100644 index 00000000..0b5ce345 --- /dev/null +++ b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb @@ -0,0 +1,104 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "98770716", + "metadata": {}, + "source": [ + "# SURF Resarch Cloud: VirtualShip environment setup\n", + "\n", + "```{note}\n", + "This guide is specific to students who are enrolled at Utrecht University.\n", + "```\n", + "\n", + "In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:\n", + "\n", + "- You aren't limited to the power of your laptop\n", + "- Input datasets are downloaded faster, as they're downloaded to the cloud instance (and not to your laptop)\n", + "\n", + "\n", + "## 1. Accepting SURF RC invite\n", + "\n", + "In your student email you'll have an invite from SURF Research Access Management (SRAM) to join a project on SURF RC. Accept this invite.\n", + "\n", + "## 2. Open the environment\n", + "\n", + "Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click \"access\" on the shared workspace.\n", + "\n", + "## 3. Jupyter workspace layout and additional config\n", + "\n", + "```{note}\n", + "This only needs to be done once during setup.\n", + "```\n", + "\n", + "In the Jupyter workspace, you'll see the following in your file explorer:\n", + "\n", + "```\n", + ".\n", + "├── KERNEL-README.ipynb\n", + "├── data\n", + "│ └── datasets\n", + "| └── shared-storage <--- The shared persistent storage\n", + "└── scratch\n", + "```\n", + "\n", + "The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., `mkdir data/shared-storage/{your-group-name}` replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n", + "\n", + "---\n", + "\n", + "To be able to run VirtualShip from the Terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb`. This contains important information for configuring your environment. Namely, for our uses, the \"Initialize conda\" section. Do the following:\n", + "\n", + "#### Initialize conda\n", + "\n", + "To make the already installed conda-tool available for yourself, you have to initialize your Terminal shell.\n", + "\n", + "Start a \"Terminal\" tab in the Jupyter Lab launcher and type: `/etc/miniconda/bin/conda init`\n", + "\n", + "Close the Terminal tab and start a new one.\n", + "You will see that the Terminal prompt has changed to something like\n", + "\n", + "```\n", + "(base) metheuser@mywsp:\n", + "```\n", + "\n", + "This is conda telling you that you are currently in the \"base\" environment.\n", + "\n", + "From here, you already have another environment set up for you. Running `conda env list` in the Terminal, you should see:\n", + "\n", + "```bash\n", + "conda env list\n", + "\n", + "# conda environments:\n", + "#\n", + "base * /etc/miniconda\n", + "virtualship /etc/miniconda/envs/virtualship`\n", + "```\n", + "\n", + "Here you can do `conda activate virtualship` to activate the environment called \"virtualship\". This environment is a shared environment among all workspace users that can be centrally updated. If you want, you can create and manage your own environments by running the relevant conda commands.\n", + "\n", + "With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-name}` and run `virtualship` commands as you would on your local machine.\n", + "\n", + "---\n", + "\n", + "Finally, when you're working in Jupyter Notebooks, you are able to access the Conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI.\n", + "\n", + "\n", + "## Course facilitator notes\n", + "\n", + "If `virtualship` is updated on GitHub, and you want to update the shared environment, you can do so by running the following commands in the Terminal:\n", + "\n", + "```bash\n", + "conda activate virtualship\n", + "sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main\n", + "```\n" + ] + } + ], + "metadata": { + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.md b/docs/user-guide/tutorials/surf_research_cloud_setup.md deleted file mode 100644 index 5b191052..00000000 --- a/docs/user-guide/tutorials/surf_research_cloud_setup.md +++ /dev/null @@ -1,84 +0,0 @@ -# SURF Resarch Cloud: VirtualShip environment setup - -```{note} -This guide is specific to students who are enrolled at Utrecht University. -``` - -In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages: - -- You aren't limited to the power of your laptop -- Input datasets are downloaded faster, as they're downloaded to the cloud instance (and not to your laptop) - -## 1. Accepting SURF RC invite - -In your student email you'll have an invite from SURF Research Access Management (SRAM) to join a project on SURF RC. Accept this invite. - -## 2. Open the environment - -Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click "access" on the shared workspace. - -## 3. Jupyter workspace layout and additional config - -```{note} -This only needs to be done once during setup. -``` - -In the Jupyter workspace, you'll see the following in your file explorer: - -``` -. -├── KERNEL-README.ipynb -├── data -│ └── datasets -| └── shared-storage <--- The shared persistent storage -└── scratch -``` - -The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., `mkdir data/shared-storage/{your-group-name}` replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit. - ---- - -To be able to run VirtualShip from the Terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb`. This contains important information for configuring your environment. Namely, for our uses, the "Initialize conda" section. Do the following: - -#### Initialize conda - -To make the already installed conda-tool available for yourself, you have to initialize your Terminal shell. - -Start a "Terminal" tab in the Jupyter Lab launcher and type: `/etc/miniconda/bin/conda init` - -Close the Terminal tab and start a new one. -You will see that the Terminal prompt has changed to something like - -``` -(base) metheuser@mywsp: -``` - -This is conda telling you that you are currently in the "base" environment. - -From here, you already have another environment set up for you. Running `conda env list` in the Terminal, you should see: - -```bash -conda env list - -# conda environments: -# -base * /etc/miniconda -virtualship /etc/miniconda/envs/virtualship` -``` - -Here you can do `conda activate virtualship` to activate the environment called "virtualship". This environment is a shared environment among all workspace users that can be centrally updated. If you want, you can create and manage your own environments by running the relevant conda commands. - -With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-name}` and run `virtualship` commands as you would on your local machine. - ---- - -Finally, when you're working in Jupyter Notebooks, you are able to access the Conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI. - -## Course facilitator notes - -If `virtualship` is updated on GitHub, and you want to update the shared environment, you can do so by running the following commands in the Terminal: - -```bash -conda activate virtualship -sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main -``` From 67df159e2697e25ed75554aae5365c54cc161ccd Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Thu, 28 Aug 2025 16:46:53 +0200 Subject: [PATCH 4/4] notes formatting --- .../tutorials/surf_research_cloud_setup.ipynb | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb index 0b5ce345..a0a28fbf 100644 --- a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb +++ b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb @@ -7,8 +7,8 @@ "source": [ "# SURF Resarch Cloud: VirtualShip environment setup\n", "\n", - "```{note}\n", - "This guide is specific to students who are enrolled at Utrecht University.\n", + "```\n", + "Note: This guide is specific to students who are enrolled at Utrecht University.\n", "```\n", "\n", "In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:\n", @@ -27,8 +27,8 @@ "\n", "## 3. Jupyter workspace layout and additional config\n", "\n", - "```{note}\n", - "This only needs to be done once during setup.\n", + "```\n", + "Note: This only needs to be done once during setup.\n", "```\n", "\n", "In the Jupyter workspace, you'll see the following in your file explorer:\n", @@ -92,6 +92,12 @@ "sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main\n", "```\n" ] + }, + { + "cell_type": "markdown", + "id": "3926833e", + "metadata": {}, + "source": [] } ], "metadata": {