Merge pull request #184 from respec/conda_tweaks

Conda tweaks and Fix Example Notebook 1

Author: PaulDudaRESPEC

README.rst

@@ -71,7 +71,7 @@ Install From Pre-built Packages
 -------------------------------
 Python Package Index (PyPI)
 +++++++++++++++++++++++++++
-Starting with version 0.11.0a1 we provide a PyPI wheel package for HSP2 which
+Starting with version 0.11.0a1 we provide `a PyPI wheel package for HSP2`_ which
 should work on any supported platform for Python 3.10, 3.11, and 3.12.
 
 .. code-block:: console
@@ -113,13 +113,17 @@ Option 1: Install using "conda"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Follow these steps to install using the conda_ package manager.
 
-1. Install the Anaconda Python Distribution
+1. Install Miniconda or Anaconda Python Distribution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Install the `latest release`_ of the Anaconda Distribution, which includes the
-conda package manager, a complete Python (and R) data science stack, and the
-Anaconda Navigator GUI.  Follow `Anaconda Installation`_ documentation.
+We recommend installing the light-weight Miniconda_ that includes Python, the 
+conda_ environment and package management system, and their dependencies.
+
+NOTE: Follow conda defaults to install in your local user directory. DO NOT 
+install for all users, to avoid substantial headaches with permissions.
+
+If you have already installed the Anaconda Distribution, you can use it to 
+complete the next steps, but you may need to update to the `latest release`_.
 
-A lighter-weight alternative is to install Miniconda_.
 
 2. Create a Conda Environment for HSP2 Modeling (optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -147,6 +151,14 @@ Install the necessary and optional packages for HSP2 in the new environment:
     cd /path/to/module/hsp2
     pip install .  # or "pip install -e ." to install in editable mode
 
+**Alternately**, you can replace all of the create and install steps above by 
+creating the new environment from the included `environment.yml` file 
+from this single line of code:
+
+.. code-block:: console
+
+    conda env create --file=environment.yml --solver=libmamba
+
 You should now be able to run the Tutorials and create your own Jupyter
 Notebooks!
 
@@ -223,6 +235,7 @@ The HSP2 API is designed to be used in Python scripts and Jupyter notebooks.
 .. _`initial release`: https://github.com/respec/HSPsquared/releases/tag/0.7.7
 .. _`GNU Affero General Public License (AGPL), copyrighted 2017 by RESPEC`: https://github.com/respec/HSPsquared/blob/master/LICENSE
 .. _JupyterLab: https://jupyterlab.readthedocs.io/en/stable/
+.. _`a PyPI wheel package for HSP2`: https://pypi.org/project/hsp2/
 .. _conda: https://docs.conda.io/en/latest/
 .. _`latest release`: https://docs.anaconda.com/anaconda/reference/release-notes/
 .. _`Anaconda Installation`: https://docs.anaconda.com/anaconda/install/

environment.yml

@@ -1,58 +1,50 @@
 ---
-name: hsp2_py38
+name: hsp2_py310
 channels:
-    - conda-forge
+  - conda-forge
+  - nodefaults  # Speeds solving env, by limiting the number of options
 
 dependencies:
-    # Aligned with Anaconda 2021.05 (May 13, 2021)
-    # package management
-    - conda
-    - conda-build
-    - pip
+  # Python 3.10 was default for Anaconda 2023.03-0 (Mar 20, 2023)
+  # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023
+  # package management
+  - conda
+  - conda-build
+  - conda-libmamba-solver
+  - pip
 
-    # Running HSP2
-    - python =3.8*
-    - scipy  # Scipy also installs numpy
-    # Pandas installs most scientific Python modules, such as Numpy, etc.
-    - pandas ==1.2.*
-    - numba ==0.53.1
-    - numpy ==1.20.*  # for compatibility with numba version <0.53
-    # latest compatible with both versions of PyTables & h5py below
-    # - doesn't work with setup.py
-    - hdf5 ==1.10.6
-    - pytables ==3.6.1
-    - h5py >=3.1
-    - hdf5plugin  # HDF5 compression filters for h5py & jupyterlab_hdf
-    - cltoolbox
+  # Running HSP2
+  - python =3.10
+  - scipy  # Scipy also installs numpy
+  # Pandas installs most scientific Python modules, such as Numpy, etc.
+  - pandas
+  - numba
+  - numpy
+  - hdf5
+  - pytables
+  - h5py
+  - hdf5plugin  # HDF5 compression filters for h5py & jupyterlab_hdf
+  - cltoolbox
 
-    # Interactivity & Visualization via Jupyter Notebooks
-    # (optional, but required for tutorials)
-    - jupyterlab ==3.0.*  #  also installs classic Jupyter notbook
-    - ipympl  # jupyter-matplotlib, https://github.com/matplotlib/ipympl
-    - nodejs  # required for many JupyterLab extensions
-    # Conda environment & package access extension from within Jupyter
-    - nb_conda
-    # HoloViz, https://holoviz.org
-    - hvplot  # hvPlot installs most HoloViz libs, including matplotlib
-    - ipywidgets  # Required for HoloViz interactivity in Jupyter notebooks
+  # Operational Model (om)
+  - pyparsing
 
-    # Dev tools (optional)
-    - python-language-server
-    # Includes both the server extension (jupyter-lsp) and pyls third-party
-    # server (python-language-server)
-    - jupyter-lsp-python
-    - jupyterlab-lsp  # Docs at https://github.com/krassowski/jupyterlab-lsp
+  # Interactivity & Visualization via Jupyter Notebooks (optional,
+  # but required for tutorials)
+  - jupyterlab  # also installs classic Jupyter notbook
+  - ipympl  # jupyter-matplotlib, https://github.com/matplotlib/ipympl
+  - nodejs  # required for many JupyterLab extensions
+  # HoloViz, https://holoviz.org
+  - hvplot  # hvPlot installs most HoloViz libs, including matplotlib
+  - ipywidgets  # Required for HoloViz interactivity in Jupyter notebooks
+  - ipywidgets_bokeh
+  - jupyter_bokeh # for VSCode
 
-    # Operational Model (om)
-    - pyparsing
+  # Dev tools (optional)
+  - python-lsp-server # Language Server Protocol (LSP) extension for Python (pylsp)
+  - jupyterlab-lsp # Provides both server extension and lab extension
 
-    # PIP install requirements only if it is not possible with conda
-    # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment
-    # Optional, but recommended for tutorials
-    - pip:
-    # https://github.com/lckr/jupyterlab-variableInspector
-    # - lckr-jupyterlab-variableinspector
-    # Explore HDF5 files in JupyterLab. Requires an additional step to install.
-    # - jupyterlab_hdf
-    # Installation instructions:
-    # https://github.com/jupyterlab/jupyterlab-hdf5#installation
+  # PIP install requirements only if it is not possible with conda
+  # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment
+  - pip:
+    - hsp2

environment_dev.yml

@@ -1,47 +1,49 @@
 ---
 name: hsp2_py311_dev
 channels:
-    - conda-forge
-    - nodefaults  # Speeds solving env, by limiting the number of options
+  - conda-forge
+  - nodefaults  # Speeds solving env, by limiting the number of options
 
 dependencies:
-    # Python 3.11 is supported by Anaconda since 2023.03-0 (Mar 20, 2023)
-    # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023
-    # package management
-    - conda
-    - conda-build
-    - conda-libmamba-solver
-    - pip
+  # Python 3.11 was default for Anaconda 2023.07-0 (Jul 11, 2023)
+  # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023
+  # package management
+  - conda
+  - conda-build
+  - conda-libmamba-solver
+  - pip
 
-    # Running HSP2
-    - python =3.11
-    - scipy  # Scipy also installs numpy
-    # Pandas installs most scientific Python modules, such as Numpy, etc.
-    - pandas >=2.0
-    - numba
-    - numpy
-    - hdf5
-    - pytables
-    - h5py
-    - hdf5plugin  # HDF5 compression filters for h5py & jupyterlab_hdf
-    # - dask  # for future performance enhancements
-    - cltoolbox
+  # Running HSP2
+  - python =3.11
+  - scipy  # Scipy also installs numpy
+  # Pandas installs most scientific Python modules, such as Numpy, etc.
+  - pandas >=2.0
+  - numba
+  - numpy
+  - hdf5
+  - pytables
+  - h5py
+  - hdf5plugin  # HDF5 compression filters for h5py & jupyterlab_hdf
+  # - dask  # for future performance enhancements
+  - cltoolbox
 
-    # Operational Model (om)
-    - pyparsing
+  # Operational Model (om)
+  - pyparsing
 
-    # Interactivity & Visualization via Jupyter Notebooks (optional,
-    # but required for tutorials)
-    - jupyterlab  # also installs classic Jupyter notbook
-    - ipympl  # jupyter-matplotlib, https://github.com/matplotlib/ipympl
-    - nodejs  # required for many JupyterLab extensions
-    # HoloViz, https://holoviz.org
-    - hvplot  # hvPlot installs most HoloViz libs, including matplotlib
-    - ipywidgets  # Required for HoloViz interactivity in Jupyter notebooks
+  # Interactivity & Visualization via Jupyter Notebooks (optional,
+  # but required for tutorials)
+  - jupyterlab  # also installs classic Jupyter notbook
+  - ipympl  # jupyter-matplotlib, https://github.com/matplotlib/ipympl
+  - nodejs  # required for many JupyterLab extensions
+  # HoloViz, https://holoviz.org
+  - hvplot  # hvPlot installs most HoloViz libs, including matplotlib
+  - ipywidgets  # Required for HoloViz interactivity in Jupyter notebooks
+  - ipywidgets_bokeh
+  - jupyter_bokeh # for VSCode
 
-    # Dev tools (optional)
-    # Language Server Protocol (LSP) extension for Python (pylsp)
-    - python-lsp-server
+  # Dev tools (optional)
+  # Language Server Protocol (LSP) extension for Python (pylsp)
+  - python-lsp-server
     # Rope for Completions and renaming
     # Pyflakes linter to detect various errors
     # McCabe linter for complexity checking
@@ -51,9 +53,10 @@ dependencies:
     # YAPF for code formatting (preferred over autopep8)
     # flake8 for error checking (disabled by default)
     # pylint for code linting (disabled by default)
-    - jupyterlab-lsp  # Provides both server extension and lab extension
+  - jupyterlab-lsp  # Provides both server extension and lab extension
 
 
-    # PIP install requirements only if it is not possible with conda
-    # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment
-    - pip:
+  # PIP install requirements only if it is not possible with conda
+  # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment
+  - pip:
+    # For Dev environment, we recommend using the `conda build` command to install