Merge pull request #21 from pp-mo/geovista_release

Update to geovista 0.1.1

Author: pp-mo

README.md

@@ -6,45 +6,18 @@ The content is all written as interactive Jupyter notebooks,
 which combine presenter information and student exercises.
 
 ## Get a suitable Python environment to run the notebooks
-A suitable fresh environment can be created from the list of required packages with conda, using :  
-e.g. `$ conda env create --name meshtut_newest_env --file tutorial_conda_env.yml` 
-
-However, this may break as newer package versions are released.
-
-So, we also provide a "lockfile" which ties down all package versions, from which a 
-known-good environment can be recreated :  
-e.g. `$ conda create --name meshtut_savefixed_env --file tutorial_conda_env_resolved.lock` 
-
-> :warning: **Important Note**  
-> For now, the latest GeoVista build in channels is not sufficient.  
-> You must also download geovista + install it, e.g. by `pip install -e .`
-### Installing Geovista :  more-or-less detailed instructions
-You need to execute commands something like this ...
-
-```bash
-$ # download
-$ cd ~/git
-$ git clone https://github.com/bjlittle/geovista.git
-$
-$ # install in the env
-$ conda activate mesh-tutorial
-$ cd ~/git/geovista
-$ pip install -e .
-  ... (lots of output) ...
-$ 
-$ # TEST that the import now works ...
-$ python -c "import geovista as gv; print(gv); print(gv.__version__)"
-<module 'geovista' from '/net/home/h05/itpp/git/geovista/src/geovista/__init__.py'>
-0.1a1.dev508
-
-$ 
-```
+
+For guaranteed operation with tested package versions, create a environment from the provided "lockfile", as follows :  
+`$ conda create --name meshtut_safelocked_env --file tutorial_conda_env_resolved.lock` 
 
 
 ## Start the tutorial
+Run Jupyter lab, in the chosen Python environment.  
+**NOTE:** _always_ start it in the `/notebooks` directory.
+
 E.G.  
 ```
-$ conda activate meshtut_savefixed_env
+$ conda activate meshtut_safelocked_env
 $ cd iris-mesh-tutorial/notebooks
 $ jupyter lab
     [I 2023-01-12 15:39:10.730 ServerApp] jupyter_server_terminals | extension was successfully linked.
@@ -63,27 +36,40 @@ $ jupyter lab
             http://localhost:8888/lab?token=c4ece2e59cd8c81779de0f394c421e22f258f50466cc027e
          or http://127.0.0.1:8888/lab?token=c4ece2e59cd8c81779de0f394c421e22f258f50466cc027e
 ```
-A window should then appear in your browser.  
+**A window should then appear in your browser.**  
 Failing that, visit one of the urls displayed in the terminal output.
 
+### Get Started
+Open the notebook `Mesh_Tutorial_Intro.ipynb`.
+
 
 ## Developer notes: to build the lockfile
-The lockfile "tutorial_conda_env_resolved.lockfile" is produced from an actual environment.
-First build the env from the spec file "tutorial_conda_env.yml" ...
+The lockfile `tutorial_conda_env_resolved.lock` is produced from an actual resolved environment.
 
-First using a conda env with "mamba" in it : resolve the env + snapshot the package list.
+To build a working env with all-latest packages, do the following : 
 
-```bash
-$ conda activate mamba-env
-$ mamba create -n mesh-tutorial --file tutorial_conda_env.yml
-$ conda list -n mesh-tutorial --explicit >temp_condalist_explicit.txt
-```
+**Step 1:** build a fresh env from the spec
 
-Then using a conda env with 'ssstack' in it (https://github.com/MetOffice/ssstack) : generate new 'shareable'-form lockfile.
+  * The env spec is in the file `tutorial_conda_env.yml`
+  * use a conda env with "mamba" in it (since conda is likely to take ages and/or run out of memory)
+  * resolve the env
+    ```bash
+    $ conda activate mamba-env
+    $ mamba env create -n mesh-tutorial --file tutorial_conda_env.yml
+    ```
+  * test that this actually _works_, by running all the notebooks
 
-```bash
-$ conda activate ssstack-env
-$ ssstack shareable temp_condalist_explicit.txt >tutorial_conda_env_resolved.lockfile
-$ rm temp_condalist_explicit.txt
-```
-      
+
+**Step 2:** make a new version of the lockfile
+
+  * use a conda env with 'ssstack' in it (https://github.com/MetOffice/ssstack)
+  * snapshot the new env content, and replace web-proxy urls to convert it to a "shareable" lockfile  
+    ```bash
+    $ conda activate ssstack-env
+    $ conda list -n mesh-tutorial --explicit >temp_condalist_explicit.txt
+    $ ssstack shareable temp_condalist_explicit.txt >tutorial_conda_env_resolved.lock
+    $ rm temp_condalist_explicit.txt
+    ```
+
+
+**Step 3:** upload changes in a PR

tutorial_conda_env.yml

@@ -5,7 +5,7 @@ dependencies:
   - python=3.9
   - iris
   - geovista
-  - vtk=9.2.2  # experiencing segfaults with latest version
+  - vtk
   - jupyterlab
   - ipyvtklink
   - jupytext=1.14.4  # changing version can cause notebook merge conflicts