diff --git a/README.md b/README.md index 55559b6..f4e107b 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,109 @@ ## About -`um2nc-standalone` is an [ACCESS-NRI](https://www.access-nri.org.au/) project to merge multiple versions of unified model conversion tools to a single, canonical project for the ESM1.5 model. +`um2nc-standalone` is a `Python3` utility to convert Unified Model data files to NetCDF format. + +The `um2nc-standalone` project is an [ACCESS-NRI](https://www.access-nri.org.au/) initiative to merge multiple versions of unified model conversion tools to a single, canonical project for the ESM1.5 model. ## Installation -TODO +These installation instructions assume deployment to a `Linux` or `MacOS` platform. -* `virtualenv` instructions -* `conda`/`miniconda`/`micromamba?` instructions +`Windows` is currently **unsupported**. -## User documentation +### Downloading `um2netcdf-standalone` -TODO +```commandline +cd +git clone https://github.com/ACCESS-NRI/um2nc-standalone.git +cd um2nc-standalone +``` + +### Installing Dependencies + +#### MacOS + +```Bash +$ brew install udunits +``` + +if this fails with some compiler/header errors, try: + +```Bash +# set up non standard cf-unit paths +$ export UDUNITS2_XML_PATH=/opt/homebrew/Cellar/udunits/2.2.28/share/udunits/udunits2.xml +$ export UDUNITS2_LIBDIR=/opt/homebrew/lib +$ export UDUNITS2_INCDIR=/opt/homebrew/Cellar/udunits/2.2.28/include +$ brew install udunits +``` + +#### Linux + +```Bash +$ apt-get install udunits +``` + +**TODO:** add `yum` commands? + +## Creating a Python Runtime Environment + +The following instructions outline two options for creating a Python runtime environment fot `um2netcdf-standalone`. The purpose of a runtime environment is to manage specific library dependencies, separately to the system python. + +`virtualenv` is a low level python environment manager, with a companion `virtualenvwrapper` project to provide greater usability. These packages are available in `apt` for Linux and `homebrew` on Mac. The following instructions assume use of `virtualenvwrapper` ([virtualenvwrapper docs](https://virtualenvwrapper.readthedocs.io/en/latest/)). + +`conda` and related tools such as `miniconda` & `micromamba` are higher level environment managers than `virtualenv. + +If you are unsure which environment manager to use and/or new to Python, `conda` is the recommended approach. + +### Creating a `virtualenv` environment + +```Bash +# assuming virtualenvwrapper has been installed & configured on your system... +# e.g. "brew install virtualenvwrapper" or "apt-get install virtualenvwrapper" +$ mkvirtualenv -r requirements.txt ums + +# should download & install multiple packages +# the command prompt should change with a (ums) prefix +``` + +### Creating a `conda` environment + +```Bash +# works for Linux and MacOS +$ conda create -n ums +$ activate ums +$ conda install pip +$ +$ cd +$ pip install -r requirements.txt +``` ### Running the tests -This project uses `pytest`. To run the tests: +The `um2nc-standalone` project uses `pytest`. To run the tests: ```Bash $ cd -$ pytest +$ pytest # should pass within seconds, possibly with warnings ``` -A minimal code coverage setup has been included, to run & generate an HTML coverage report: +A minimal code coverage setup has been included, to run the tests & generate an HTML coverage report: -``` +```Bash $ cd $ pytest --cov-report=html --cov=umpost ``` Then load the `index.html` from the project root/coverage_html dir. +## User documentation + +TODO: this needs to cover: + +1. Running `um2netcdf` standalone +2. Using the workflow run script +3. Using `um2netcdf` as an API + ## Further information TODO diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..54d5b33 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,55 @@ +antlr4-python3-runtime==4.7.2 +asttokens==2.4.1 +Cartopy==0.23.0 +certifi==2024.6.2 +cf-units==3.2.0 +cftime==1.6.4 +click==8.1.7 +cloudpickle==3.0.0 +contourpy==1.2.1 +coverage==7.6.0 +cycler==0.12.1 +dask==2024.6.0 +decorator==5.1.1 +executing==2.0.1 +f90nml==1.4.4 +fonttools==4.53.0 +fsspec==2024.6.0 +iniconfig==2.0.0 +ipython==8.25.0 +jedi==0.19.1 +Jinja2==3.1.4 +kiwisolver==1.4.5 +locket==1.0.0 +MarkupSafe==2.1.5 +matplotlib==3.9.0 +matplotlib-inline==0.1.7 +mule @ git+https://github.com/metomi/mule@cce4b99c7046217b1ec1192118a786636e0d8e54#subdirectory=mule +netCDF4==1.7.1 +numpy==1.26.4 +packaging==24.1 +parso==0.8.4 +partd==1.4.2 +pexpect==4.9.0 +pillow==10.3.0 +pluggy==1.5.0 +prompt_toolkit==3.0.47 +ptyprocess==0.7.0 +pure-eval==0.2.2 +Pygments==2.18.0 +pyparsing==3.1.2 +pyproj==3.6.1 +pyshp==2.3.1 +pytest==8.2.2 +pytest-cov==5.0.0 +python-dateutil==2.9.0.post0 +PyYAML==6.0.1 +scipy==1.13.1 +scitools-iris==3.9.0 +shapely==2.0.4 +six==1.16.0 +stack-data==0.6.3 +toolz==0.12.1 +traitlets==5.14.3 +wcwidth==0.2.13 +xxhash==3.4.1