From 1c1afa5518ce66d4c568706001e6dbc32a754324 Mon Sep 17 00:00:00 2001 From: Jonathan Guyer Date: Tue, 12 Dec 2023 16:00:42 -0500 Subject: [PATCH] Merge base-environment.yml into solver environments Easier to explain and less fragile, at the expense of redundancy in individual environment.yml files. It's a shame they don't have an include mechanism. Refactored environment documentation into environments/README.rst. --- .azure/templates/install.yml | 6 +- INSTALLATION.rst | 130 ++++++++------------------ docs/source/ADMINISTRATA.rst | 1 - docs/source/CONDA_ENVIRONMENT.rst | 1 + environments/README.rst | 87 +++++++++++++++++ environments/base-environment.yml | 12 --- environments/petsc-environment.yml | 9 ++ environments/pysparse-environment.yml | 11 ++- environments/scipy-environment.yml | 8 ++ environments/trilinos-environment.yml | 9 ++ 10 files changed, 162 insertions(+), 112 deletions(-) create mode 100644 docs/source/CONDA_ENVIRONMENT.rst create mode 100644 environments/README.rst delete mode 100644 environments/base-environment.yml diff --git a/.azure/templates/install.yml b/.azure/templates/install.yml index 8d46f8911e..aee4234db2 100644 --- a/.azure/templates/install.yml +++ b/.azure/templates/install.yml @@ -49,12 +49,8 @@ steps: # Daily midnight build uses environment.yml files to catch regressions # due to updates in dependencies - bash: | - python -m pip install conda-merge - conda-merge environments/base-environment.yml \ - environments/${{ parameters.solver }}-environment.yml \ - > environments/merged-environment.yml conda env create --name myEnvironment \ - --file environments/merged-environment.yml + --file environments/${{ parameters.solver }}-environment.yml displayName: Create Anaconda environment from environments condition: eq(variables['Build.CronSchedule.DisplayName'], 'Daily midnight build') diff --git a/INSTALLATION.rst b/INSTALLATION.rst index ac4ec2c44a..54172fed2f 100644 --- a/INSTALLATION.rst +++ b/INSTALLATION.rst @@ -66,118 +66,62 @@ Recommended Method These days, the most useful channel is conda-forge_, which provides everything necessary to install :term:`FiPy`. -* `install Miniconda`_ on your computer -* Install :term:`FiPy` :ref:`REQUIREDPACKAGES` with one of the following: +Install conda_ +============== - * Conda environment files:: +`Install conda`_ or `install micromamba`_ on your computer. - $ conda env create --name \ - --file environments/base-environment.yml - followed by:: +.. include:: CONDA_ENVIRONMENT.rst - $ conda env update --name \ - --file environments/-environment.yml - You can try to include multiple solver suites, but be aware that - different suites may have incompatible requirements, or may restrict - installation to obsolete versions of Python. Given that :term:`FiPy` - can only use one solver suite during a run, installing more than one - solver in an environment isn't necessary. +Install :term:`FiPy` +==================== - .. attention:: - - Successively updating an environment can be unpredictable, as - later packages may conflict with earlier ones. Unfortunately, - ``conda env create`` `does not support multiple environment files - `_. - - Alternatively, combine :file:`environments/base-environment.yml` - with any :file:`environments/-environment.yml` you wish to - use (`conda-merge `_ may - prove useful). Then execute:: - - $ conda env create --name --file .yml - - * `conda-lock `_ lockfiles:: - - $ conda-lock install --name \ - environments/locks/conda--lock.yml - - or, to be really explicit:: - - $ conda create --name \ - --file environments/locks/conda--.lock - - These lockfiles list the specific package versions used to test - :term:`FiPy` and should provide the most reproducible environment. - - * Directly from conda-forge_, picking and choosing desired packages, e.g.:: - - $ conda create --name --channel conda-forge \ - python=3 numpy scipy matplotlib-base future packaging mpich \ - mpi4py petsc4py mayavi "gmsh <4.0|>=4.5.2" - - or:: - - $ conda create --name --channel conda-forge \ - python=2.7 numpy scipy matplotlib-base future packaging \ - pysparse mayavi "traitsui<7.0.0" "gmsh<4.0" - - .. attention:: - - Bit rot has started to set in for Python 2.7. One consequence is that - :class:`~fipy.viewers.vtkViewer.VTKViewer`\s can raise errors - (probably other uses of :term:`Mayavi`, too). Hence, the constraint - of `"traitsui<7.0.0"`. - - .. note:: - - Each of these commands create a self-contained conda_ environment and - then download and populate the environment with the prerequisites for - :term:`FiPy` from the conda-forge_ channel at https://anaconda.org. - -* Install :term:`FiPy` itself:: +:: $ conda install --name --channel conda-forge fipy - .. note:: +.. note:: + + The `fipy conda-forge`_ package used to be "batteries included", but + we found this to be too fragile. It now only includes the bare + minimum for :term:`FiPy` to function. - The `fipy conda-forge`_ package used to be "batteries included", but - we found this to be too fragile. It now only includes the bare - minimum for :term:`FiPy` to function. +Enable conda_ environment +========================= -* enable this new environment with:: +Enable your new environment with:: $ conda activate - or +or:: $ source activate - .. note:: +or, on Windows_:: - ``$ activate `` on Windows_ + $ activate -* move on to :ref:`USAGE`. +You're now ready to move on to :ref:`USAGE`. - .. note:: +.. note:: - conda_ can be - `quite `_ - `slow `_ - to resolve all dependencies when performing - an installation. You may wish to consider using the alternative - mamba_ installation manager to speed things up. + conda_ can be + `quite `_ + `slow `_ + to resolve all dependencies when performing + an installation. You may wish to consider using the alternative + mamba_ installation manager to speed things up. - .. note:: +.. note:: - On Linux_ and `Mac OS X`_, you should have a pretty complete system - to run and visualize :term:`FiPy` simulations. On Windows_, there - are fewer packages available via conda_, particularly amongst the - sparse matrix :ref:`SOLVERS`, but the system still should be - functional. Significantly, you will need to download and install - :term:`Gmsh` manually when using Python 2.7. + On Linux_ and `Mac OS X`_, you should have a pretty complete system + to run and visualize :term:`FiPy` simulations. On Windows_, there + are fewer packages available via conda_, particularly amongst the + sparse matrix :ref:`SOLVERS`, but the system still should be + functional. Significantly, you will need to download and install + :term:`Gmsh` manually when using Python 2.7. .. attention:: @@ -185,8 +129,8 @@ Recommended Method its :ref:`examples `. These can be obtained by `cloning the repository`_ or downloading a `compressed archive`_. -.. _install Miniconda: https://conda.io/projects/conda/en/latest/user-guide/install -.. _guyer: https://anaconda.org/guyer +.. _install conda: https://conda.io/projects/conda/en/latest/user-guide/install/ +.. _install micromamba: https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html .. _conda-forge: https://conda-forge.github.io/ .. _Mac OS X: http://www.apple.com/macosx/ .. _Linux: http://www.linux.org/ @@ -406,8 +350,8 @@ of the system package manager and the system directories. These utilities include conda_, Nix_, Stow_, Virtualenv_ and Buildout_, amongst others. Conda_ and Nix_ are only ones of these we have the resources to support. -Our preferred development environment is set up with the initial steps of -the :ref:`RECOMMENDED_METHOD`, without :term:`FiPy` itself, followed by:: +Our preferences is to :ref:`CREATE_CONDA_ENVIRONMENT` for development, +followed by:: $ source activate $ python -m pip install scikit-fmm diff --git a/docs/source/ADMINISTRATA.rst b/docs/source/ADMINISTRATA.rst index 9dde886809..136ef203f3 100644 --- a/docs/source/ADMINISTRATA.rst +++ b/docs/source/ADMINISTRATA.rst @@ -129,7 +129,6 @@ The `conda-lock `_ lockfiles in $ for solver in petsc pysparse scipy trilinos do conda-lock lock \ - --file environments/base-environment.yml \ --file environments/${solver}-environment.yml \ --lockfile environments/locks/conda-${solver}-lock.yml conda-lock render \ diff --git a/docs/source/CONDA_ENVIRONMENT.rst b/docs/source/CONDA_ENVIRONMENT.rst new file mode 100644 index 0000000000..1786e5fb0c --- /dev/null +++ b/docs/source/CONDA_ENVIRONMENT.rst @@ -0,0 +1 @@ +.. include:: ../../environments/README.rst diff --git a/environments/README.rst b/environments/README.rst new file mode 100644 index 0000000000..26694e7eb3 --- /dev/null +++ b/environments/README.rst @@ -0,0 +1,87 @@ +.. _CREATE_CONDA_ENVIRONMENT: + +Create a conda_ environment +=========================== + +Use one of the following methods to create a self-contained conda_ +environment and then download and populate the environment with the +prerequisites for :term:`FiPy` from the conda-forge_ channel at +https://anaconda.org. + +* Conda_ environment files + + This option is the most upgradable in the future and probably the best + for development. + + :: + + $ conda env create --name \ + --file environments/-environment.yml + + .. note:: + + You can try to include multiple solver suites using ``conda env + update``, but be aware that different suites may have incompatible + requirements, or may restrict installation to obsolete versions of + Python. Given that :term:`FiPy` can only use one solver suite during + a run, installing more than one solver in an environment isn't + necessary. + + .. attention:: + + Successively updating an environment can be unpredictable, as later + packages may conflict with earlier ones. Unfortunately, ``conda + env create`` `does not support multiple environment files + `_. + + Alternatively, combine the different + :file:`environments/-environment.yml` files you wish to + use, along with `environment.yml` files for any other packages you + are interested in (`conda-merge + `_ may prove useful). + Then execute:: + + $ conda env create --name --file .yml + +* conda-lock_ lockfiles + + This option will pin all the packages, so is the most reproducible, but + not particularly upgradable. For most, this is the safest way to + generate a FiPy environment that consistently works. + + :: + + $ conda-lock install --name \ + environments/locks/conda--lock.yml + + or, to be really explicit (and obviating the need for conda-lock_):: + + $ conda create --name \ + --file environments/locks/conda--.lock + +* Directly from conda-forge_, picking and choosing desired packages + + This option is the most flexible, but has the highest risk of missing or + incompatible packages. + + e.g.:: + + $ conda create --name --channel conda-forge \ + python=3 numpy scipy matplotlib-base future packaging mpich \ + mpi4py petsc4py mayavi "gmsh <4.0|>=4.5.2" + + or:: + + $ conda create --name --channel conda-forge \ + python=2.7 numpy scipy matplotlib-base future packaging \ + pysparse mayavi "traitsui<7.0.0" "gmsh<4.0" + + .. attention:: + + Bit rot has started to set in for Python 2.7. One consequence is that + :class:`~fipy.viewers.vtkViewer.VTKViewer`\s can raise errors + (probably other uses of :term:`Mayavi`, too). Hence, the constraint + of `"traitsui<7.0.0"`. + +.. _conda-lock: https://github.com/conda/conda-lock + diff --git a/environments/base-environment.yml b/environments/base-environment.yml deleted file mode 100644 index 0c74de73b6..0000000000 --- a/environments/base-environment.yml +++ /dev/null @@ -1,12 +0,0 @@ -channels: - - conda-forge -dependencies: - - python - - numpy - - scipy - - matplotlib-base - - future - - packaging - - mayavi - - gmsh <4.0|>=4.5.2 - - pip diff --git a/environments/petsc-environment.yml b/environments/petsc-environment.yml index 09290a4d95..62ecc7a1b4 100644 --- a/environments/petsc-environment.yml +++ b/environments/petsc-environment.yml @@ -1,6 +1,15 @@ channels: - conda-forge dependencies: + - python + - numpy + - scipy + - matplotlib-base + - future + - packaging + - mayavi + - gmsh <4.0|>=4.5.2 + - pip - mpich - mpi4py # petsc 3.20.2_*_102 is broken on macOS, diff --git a/environments/pysparse-environment.yml b/environments/pysparse-environment.yml index 4031fc07b4..ca3cbec6dd 100644 --- a/environments/pysparse-environment.yml +++ b/environments/pysparse-environment.yml @@ -1,8 +1,17 @@ channels: - conda-forge dependencies: - - pysparse + - python + - numpy + - scipy + - matplotlib-base + - future + - packaging - mayavi # [unix] + - traitsui <7.0.0 + - gmsh <4.0|>=4.5.2 + - pip + - pysparse platforms: - linux-64 - osx-64 diff --git a/environments/scipy-environment.yml b/environments/scipy-environment.yml index 4e07e6f0e8..01466ef795 100644 --- a/environments/scipy-environment.yml +++ b/environments/scipy-environment.yml @@ -3,4 +3,12 @@ channels: - conda-forge dependencies: + - python + - numpy - scipy + - matplotlib-base + - future + - packaging + - mayavi + - gmsh <4.0|>=4.5.2 + - pip diff --git a/environments/trilinos-environment.yml b/environments/trilinos-environment.yml index 3131188eb2..33233023b2 100644 --- a/environments/trilinos-environment.yml +++ b/environments/trilinos-environment.yml @@ -1,6 +1,15 @@ channels: - conda-forge dependencies: + - python + - numpy + - scipy + - matplotlib-base + - future + - packaging + - mayavi + - gmsh <4.0|>=4.5.2 + - pip - mpich - mpi4py - pytrilinos