Installation instructions

[navidcy]

We should include some installations instructions (at the moment how to install the package from Github) both via conda or pip. We should also include description of dependencies and ESMF/xESMF-shenanigans.

cc @angus-g

[navidcy]

I tried to create an empty conda env and then do

conda install pip
pip install git+https://github.com/COSIMA/regional-mom6.git

This worked, but then:

$ python3                                                                        [13:42:26]
Python 3.11.4 | packaged by conda-forge | (main, Jun 10 2023, 18:08:41) [Clang 15.0.7 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import regional_mom6
Traceback (most recent call last):
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/xesmf/backend.py", line 22, in <module>
    import esmpy as ESMF
ModuleNotFoundError: No module named 'esmpy'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/regional_mom6/__init__.py", line 6, in <module>
    from .regional_mom6 import *  # noqa
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/regional_mom6/regional_mom6.py", line 8, in <module>
    import xesmf as xe
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/xesmf/__init__.py", line 4, in <module>
    from .frontend import Regridder, SpatialAverager
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/xesmf/frontend.py", line 12, in <module>
    from .backend import Grid, LocStream, Mesh, add_corner, esmf_regrid_build, esmf_regrid_finalize
  File "/Users/navid/Research/test_mom6/env/lib/python3.11/site-packages/xesmf/backend.py", line 24, in <module>
    import ESMF
ModuleNotFoundError: No module named 'ESMF'
>>>

Any ideas? It's related to the ESMF/xesmf shenanigans I guess? Probably because pip doesn't look into the environment.yml for deps, right?

[angus-g]

That's correct, you need to install ESMF through Conda/externally, and all the other dependencies are requested by the package itself. That's why we use the environment-ci.yml file when setting up the test runner (but that could probably be incorporated into the Conda installation instructions).

I think ideally we'd provide a Conda package that handles all the dependencies on that side. For the pip side, the regular package can go on PyPI, but require an external ESMF to be provided for it to work.

[navidcy]

I presume when we push to conda-forge we can do that. But as far I understood by googling you can't install a package directly from Github via conda. So at the moment, we are left with pip install git+... and thus we need to manually install emspy via conda ourselves before that.

That's what I had to do in #58; happy for any suggestions to smooth out that installation workflow!