Add Pixi documentation

alliance-computing.rst

@@ -240,8 +240,9 @@ You should be able to follow these instructions to set up on any of the other Al
    and run NEMO.
 
 #. Follow the :ref:`salishseadocs:InstallCommandProcessorPackages` docs to install the
-   :ref:`salishseacmd:SalishSeaCmdProcessor` and its dependencies in a
-   :command:`conda`  environment.
+   :ref:`salishseacmd:SalishSeaCmdProcessor` and its dependencies with `Pixi`_.
+
+   .. _Pixi: https://pixi.prefix.dev/latest/
 
 #. Follow the :ref:`BuildXIOS-MEOPAR-nibi` docs to build ``XIOS-2``.
 

getting_started.rst

@@ -35,7 +35,7 @@ Here's the Getting Started checklist:
 #. :ref:`SetUpSecureRemoteAccess`
 #. :ref:`SetUpGit`
 #. :ref:`SetUpBash`
-#. :ref:`InstallMiniforge`
+#. :ref:`InstallPixi`
 #. :ref:`SetUpYourAnalysisRepository`
 
 
@@ -109,16 +109,15 @@ before you can:
 on a Waterhole workstation.
 
 
-.. _InstallMiniforge:
+.. _InstallPixi:
 
-Install Miniforge
-=================
+Install Pixi
+============
 
 You will need to:
 
-#. Learn about :ref:`MOAD-CondaPkgAndEnvMgr`
-#. :ref:`Install Miniforge<InstallingMiniforge>` on your laptop
-#. :ref:`Install Miniforge<InstallingMiniforge>` in your workspace on the EOAS Ocean collection of Linux computers
+#. Learn about :ref:`MOAD-PixiPkgAndEnvMgr`
+#. :ref:`Install Pixi<InstallingPixi>` in your workspace on the EOAS Ocean collection of Linux computers
 
 
 .. _SetUpYourAnalysisRepository:
@@ -129,6 +128,6 @@ Set Up Your Analysis Repository
 You will need to have:
 
 #. :ref:`SetUpGit`
-#. :ref:`Installed Miniforge<InstallMiniforge>`
+#. :ref:`Installed Pixi<InstallPixi>`
 
 before you can set up your :ref:`analysis repository<MOAD-AnalysisRepository>`.

index.rst

@@ -12,7 +12,12 @@
 UBC EOAS MOAD Group Documentation
 *********************************
 
-This is documentation by and for members of the MOAD (Mesoscale Ocean and Atmospheric Dynamics) group in the EOAS (Earth, Ocean, and Atmospheric Sciences) department at UBC (the University of British Columbia).
+This is documentation by and for members of the MOAD
+(Mesoscale Ocean and Atmospheric Dynamics)
+group in the EOAS
+(Earth, Ocean, and Atmospheric Sciences)
+department at UBC
+(University of British Columbia).
 
 
 .. toctree::
@@ -24,7 +29,7 @@ This is documentation by and for members of the MOAD (Mesoscale Ocean and Atmosp
    vcs_repos
    git_version_control
    bash_config
-   conda_pkg_env_mgr
+   pixi/index
    analysis_repo
    python
    jupyter

pixi/index.rst

@@ -0,0 +1,34 @@
+.. Copyright 2018 – present by The UBC EOAS MOAD Group
+.. and The University of British Columbia
+..
+.. Licensed under a Creative Commons Attribution 4.0 International License
+..
+..   https://creativecommons.org/licenses/by/4.0/
+
+
+.. _MOAD-PixiPkgAndEnvMgr:
+
+************************************
+Pixi Package and Environment Manager
+************************************
+
+`Pixi`_ is a tool for managing software packages and environments.
+It is designed to be fast, reproducible, and easy to use across different operating systems (Windows, macOS, and Linux).
+
+.. _Pixi: https://pixi.prefix.dev/latest/
+
+For users with minimal experience in Python dependency management,
+Pixi simplifies many complex tasks into a single tool.
+
+`This notebook`_ is from the 16-Apr-2026 group discussion in which Doug introduced Pixi.
+
+.. _This notebook: https://github.com/UBC-MOAD/PythonNotes/blob/main/pkgs-envs/PythonPkgsEnvsSlides-2026.ipynb
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   pixi_pkg_env_mgr
+   pixi_SalishSeaCmd
+   pixi_analysis_repo

pixi/pixi_SalishSeaCmd.rst

@@ -0,0 +1,172 @@
+.. Copyright 2018 – present by The UBC EOAS MOAD Group
+.. and The University of British Columbia
+..
+.. Licensed under a Creative Commons Attribution 4.0 International License
+..
+..   https://creativecommons.org/licenses/by/4.0/
+
+
+.. _MigratingToPixiPoweredSalishSeaCmd:
+
+**************************************
+Migrating to Pixi-Powered SalishSeaCmd
+**************************************
+
+If you are running NEMO on one of the Alliance HPC clusters,
+an easy way to start using Pixi is to migrate your :py:obj:`SalishSeaCmd` installation
+and workflow to Pixi.
+The steps are:
+
+#. Install Pixi on the Alliance cluster
+   (if you have not already done so)
+#. Pull the most recent version of :py:obj:`SalishSeaCmd` from GitHub
+#. Use Pixi to to create an isolated environment for :py:obj:`SalishSeaCmd`
+#. Use :command:`pixi run salishsea run...` to launch a run
+#. Clean up the elements of your old conda-powered installation
+
+
+Install Pixi
+============
+
+.. code-block:: console
+
+    $ curl -fsSL https://pixi.sh/install.sh | bash
+
+Having Pixi autocomplete its sub-commands,
+option flags,
+environment names,
+etc.
+when you hit :kbd:`Tab` is very convenient.
+To enable that,
+add the following line to your :file:`$HOME/.bashrc` file:
+
+.. code-block:: bash
+
+    eval "$(pixi completion --shell bash)"
+
+After installation, please restart your terminal session to finalize the installation.
+
+
+Update :py:obj:`SalishSeaCmd`
+=============================
+
+.. code-block:: console
+
+    $ cd $HOME/SalishSeaCmd/
+    $ git pull
+
+.. note::
+   Depending on when you set up :py:obj:`SalishSeaCmd` on the cluster,
+   it is possible that its path is different to :file:`$HOME/MEOPAR/SalishSeaCmd/`.
+   The next most likely possibility is :file:`$PROJECT/$USER/MEOPAR/SalishSeaCmd/`.
+
+
+Create the :py:obj:`SalishSeaCmd` Environment
+=============================================
+
+.. code-block:: console
+
+    $ pixi install
+
+
+Use :command:`pixi run salishsea run...`
+========================================
+
+When you are in the :file:`SalishSeaCmd/` directory
+(or a sub-directory)
+you can run the :program:`salishsea` command with with the :command:`pixi run` command.
+Example:
+
+.. code-block:: console
+
+    $ pixi run salishsea help
+
+A common use-case is to execute the :command:`salishsea run` command in the directory containing
+your run description YAML file.
+To accomplish that,
+you have to tell Pixi where to find the :file:`SalishSeaCmd/` directory so that it can use the
+correct environment.
+You do that by using the ``-m`` or ``--manifest`` option of :command:`pixi run`.
+Example:
+
+.. code-block:: console
+
+    $ cd SS-run-sets/SalishSea/sea/Carbon_v202111/
+    $ pixi run -m $HOME/MEOPAR/SalishSeaCmd salishsea run 01jan11_Lb80.yaml \
+        /scratch/allen/Carbon/MoreSens/Now/01jan11/
+
+
+Cleanup
+=======
+
+#. Uninstall :py:obj:`SalishSeaCmd` from :file:`$HOME/.local/bin/`
+
+   .. code-block:: console
+
+      $ conda activate salishsea-cmd
+      $ python -m pip uninstall SalishSeaCmd
+
+#. Uninstall :py:obj:`NEMO-Cmd` from :file:`$HOME/.local/bin`
+
+   .. code-block:: console
+
+      $ python -m pip uninstall NEMO-Cmd
+
+#. Remove your ``salishsea-cmd`` conda environment
+
+   .. code-block:: console
+
+      $ conda deactivate salishsea-cmd
+      $ conda env remove -n salishsea-cmd
+
+#. Remove your :py:obj:`NEMO-Cmd` repository clone
+
+   Installation and updating of :py:obj:`NEMO-Cmd` is now handled by Pixi because :py:obj:`NEMO-Cmd`
+   is now an implicit dependency for :py:obj:`SalishSeaCmd` in its manifest file.
+   So,
+   you can remove your :py:obj:`NEMO-Cmd` repository clone:
+
+   .. code-block:: console
+
+      $ rm -rf $HOME/MEOPAR/NEMO-Cmd/
+
+   .. note::
+      Depending on when you set up :py:obj:`SalishSeaCmd` on the cluster,
+      it is possible that the path is different to :file:`$HOME/MEOPAR/NEMO-Cmd/`.
+      The next most likely possibility is :file:`$PROJECT/$USER/MEOPAR/NEMO-Cmd/`.
+
+#. Remove ``NEMO-Cmd`` from the ``vcs revisions:`` sections of your run description YAML files.
+
+   If you don't you will get warnings like:
+
+   .. code-block:: output
+      :class: no-copybutton
+
+      nemo_cmd.prepare WARNING: revision and status requested for non-existent repo: /home/dlatorne/MEOPAR/NEMO-Cmd
+
+   every time you use :command:`pixi run salishsea run ...`
+
+#. Remove conda (if the only environment left is ``base``)
+
+   If the output of:
+
+   .. code-block:: console
+
+      $ conda env list
+
+   shows only the ``base`` environment like:
+
+   .. code-block:: output
+      :class: no-copybutton
+
+      # conda environments:
+      #
+      base                     /home/allen/miniforge3
+
+   follow the `Uninstall instructions`_ for Miniforge to remove it.
+
+   .. _Uninstall instructions: https://github.com/conda-forge/miniforge#uninstall
+
+   If you have environments in addition to ``base`` left,
+   migrate them to Pixi before you remove conda.
+   Please contact Doug if you need help.