diff --git a/README.rst b/README.rst
index 024a4018dfdb4988666c534e95e126144c6678ad..92c4b43f8cc81d7e14ef93ec30985914628617e8 100644
--- a/README.rst
+++ b/README.rst
@@ -1,10 +1,11 @@
PyNEMO
======
-To be updated soon. This work springboards from the `PyNEMO Project <http://pynemo.readthedocs.io/en/latest/index.html/>`_.
+Full documentation here.
What is this repository for?
----------------------------
+PyNEMO boundary generation toolbox for NEMO ocean model.
How do I get set up?
--------------------
diff --git a/docs/source/CMEMS_downloader_usage.rst b/docs/source/CMEMS_downloader_usage.rst
index af6104b14d7f9a97953b6c8b16b383e9b3751d84..83536f8445bdf075840b26950bd8106ea92853ad 100644
--- a/docs/source/CMEMS_downloader_usage.rst
+++ b/docs/source/CMEMS_downloader_usage.rst
@@ -124,7 +124,7 @@ Extent configuration
---------------------
Finally the last box, this is where the extent to download is configured, it is up to the user to decide but it is suggested this
-is at least 1 degree wider than the destination configuration. The depth range to request is also defined here. This information can
+is at least 1 degree wider than the destination or child configuration. The depth range to request is also defined here. This information can
be extracted from the CMEMS catalogue. Once set for a given configuration this will not need to be edited.
diff --git a/docs/source/_static/eg1.png b/docs/source/_static/eg1.png
new file mode 100644
index 0000000000000000000000000000000000000000..37a6e29ba78b721b8bd781a5a1c4f79ad4f68949
Binary files /dev/null and b/docs/source/_static/eg1.png differ
diff --git a/docs/source/_static/example_bdy_coords.png b/docs/source/_static/example_bdy_coords.png
new file mode 100644
index 0000000000000000000000000000000000000000..cd83e138a1bc0d264fabd8c3c0e25c2686696aa2
Binary files /dev/null and b/docs/source/_static/example_bdy_coords.png differ
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 0f7a7435419d31648c430e95c57d5e3d6c9059f5..7e23fc7faf4320d2b785877b775d51a63f1434b3 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -4,49 +4,121 @@ This page provides a guide to installing pyNEMO.
Dependencies
^^^^^^^^^^^^
+anaconda:
+ - basemap=1.2.0
+ - netcdf4=1.5.3
+ - pyqt=5.9.2
+ - scipy=1.2.1
+ - python=3.7.6
+ - pip=20.0.2
+ - pandas=1.0.1
+ - pytest=5.3.5
+ - xarray=0.15.0
-1. Python 2.7 (Not tested with 3.x)
-2. scipy
-3. netCDF4-python
-4. numpy
-5. matplotlib
-6. basemap
-7. thredds_crawler
-8. seawater
-9. pyjnius (optional)
+pip:
+ - idna==2.9
+ - lxml==4.5.0
+ - pyjnius==1.2.1
+ - seawater==3.3.4
+ - thredds-crawler==1.5.4
+ - motuclient==1.8.4
+ - sphinx==3.0.2
+ - sphinx-rtd-theme==0.4.3
-Anaconda
-^^^^^^^^
+How do I install PyNEMO?
+------------------------
-Using conda: pyNEMO supports Win64, OSX and Linux. for other operating systems please build from source.
+Steps to take to install PyNEMO, creating a specific conda virtual environment is highly recommended.
+`click here for more about virtual enviroments <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html/>`_
-.. note:: It is recommended to create a seperate virtual environment for pyNEMO.
- Please follow the instructions on doing this at http://www.continuum.io/blog/conda
+- Install Git (outside scope of this guide)
+- Clone PyNEMO repository::
-::
+ $ git clone https://github.com/NOC-MSM/PyNEMO.git
- conda install -c https://conda.anaconda.org/srikanthnagella pynemo
+- Install Conda, either Anaconda or Miniconda (outside scope of this guide)
+- Create conda environment for PyNEMO::
-This will install pynemo and its dependencies. This build is generally outdated as development and
-bug fixes to the source are a regular occurrence. It may be better to install from source until a beta
-release is available.
+ $ cd PyNEMO
+ $ conda env create -f pynemo_37.yml
-From Source
-^^^^^^^^^^^
+- Activate the new virtual environment::
-Installing pyNEMO using other flavours of software or from source. Install all the dependencies and
-download the source code from svn and install.
+ $ source activate pynemo3
-::
+- Install Jave JDK (outside scope of this guide) and link Java Home to conda environment::
- svn checkout http://ccpforge.cse.rl.ac.uk/svn/pynemo/trunk/Python/
- python setup.py install
-
-.. note:: If building from source in the Anaconda environment all dependencies can
- be installed using conda apart from thredds_crawler and pyjnius which can
- be installed using the following Anaconda channel:
+ $ export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-13.0.2.jdk/Contents/Home # see notes below
+
+**NOTE** this link has to be set everytime the enviornment is activated. It can be automated using the .bashrc file or by
+setting environment hooks in the conda activate and deactivate files.
+
+- Install PyNEMO::
+
+ $ cd /location/of/pynemo/repo
+ $ python setup.py build
+ $ python setup.py install
+
+This should result in PyNEMO being installed in the virtual environment, and can be checked by entering::
+
+ $ pynemo -h
+
+Resulting in a help usage prompt::
+
+ $ usage: pynemo [-g] -s -d <namelist.bdy>
+ -g (optional) will open settings editor before extracting the data
+ -s <bdy filename> file to use
+ -d (optional) will download CMEMS data using provided bdy file
+
+The virtual environment can be deactivated to return you to the normal prompt by typing::
+
+ $ conda deactivate
+
+To reactivate, the following needs to be typed::
+
+ $ source activate pynemo3
+
+
+Jave Home Environment path
+--------------------------
+
+The above path for Java Home was valid for a Macbook Pro 2015 with macOS Catalina and Java SDK 13.0.2
+however for different java versions, operating systems etc this may be different
+
+The conda environment yaml file has been tested with miniconda 3.7 and found to install the environment correctly.
+
+Bench Marking Tests
+-------------------
+
+The PyNEMO module can be tested using the bench marking namelist bdy file in the inputs folder. To check the outputs of the benchmark test, these can be visualised using the plotting script within the test_scripts folder. The following steps are required,
+
+- Run PyNEMO using the namelist file in the inputs folder (namelist_remote.bdy) e.g.::
+
+ $ pynemo -s /path/to/namelist/file
+
+- This will create two output files coordinates.bdy.nc and NNA_R12_bdyT_y1979)m11.nc in an outputs folder
+
+- To check the coordinates.bdy.nc has the correct boundary points, the script bdy_coords_plot.py will plot the domain boundaries and shown the different locations of the rim width (increasing number should go inwards) This script is located in the test_scripts folder.
+
+- The result should look like this (if using the current benchmark data)
+
+.. image:: /_static/example_bdy_coords.png
+ :width: 800
+ :alt: Example BDY coords output
+
+Unit Tests
+-----------
+
+To test operation of the PyNEMO module, running the PyTest script in the unit tests folder will perform a range of tests on different child grids,
+e.g. checking the interpolation of the source data on to the child grid. To do this the following command is required::
+
+ $ pytest -v pynemo/pynemo_unit_test.py
+
+The results of the test will show if all tests pass or the errors that result from failed tests.
+
+Currently **(26/03/2020)** there are 7 tests that cover checking the interpolation results of different child grids. The input data is generated as part of the
+test and is removed afterwards. The number of tests will be increased in the future to cover more PyNEMO functionality.
+
+For more information regarding the use and development of PyNEMO see: [PyNEMO Wiki](https://github.com/jdha/PyNEMO/wiki)
-::
- conda install -c https://conda.anaconda.org/srikanthnagella thredds_crawler
- conda install -c https://conda.anaconda.org/srikanthnagella pyjnius
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index fd1a6c32114908bd0de0c39d497ef104fae96363..e0835e528be3d05c7348c19192a07e303249e6c9 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -1,18 +1,23 @@
Usage
=====
-There are two tools available in pyNEMO. They are described in detail below.
-
-pynemo
-------
-
-This command line tool reads a BDY file, extracts boundary data and prepares
-the data for a NEMO simulation. The bdy file is a plain text file containing
-key value pairs. Please look at the sample `namelist.bdy
-<http://ccpforge.cse.rl.ac.uk/gf/project/pynemo/scmsvn/?action=browse&path=%2Ftrunk%2FPython%2Fdata%2Fnamelist.bdy&view=markup>`_
-file, which shares common syntax with the NEMO simulation namelist input file.
-
-.. note:: Directory paths in bdy file can be relative or absolute.
- The application picks the relative path from the current working
+There are four tools available in pyNEMO. These are "boundary file generation" where boundary data files are generated from a
+parent grid along the boundary of a child grid. Boundary data can comprise of tracers such as temperature and salinity. Or
+tidal data from global tide models. Sea surface height and ocean currents are also supported. PyNEMO now has an integrated
+CMEMS repository downloaded. Invoking this option will download data of interest for a region of interest. PyNEMO uses NCML
+files to define variable names and data location. this allows multiple netcdf input files to appear as one. This commonmly used
+on THREDDS servers but is also used locally for CMEMS boundary data input. The GUI allows this NCML files to be generated.
+Finally there is a settings editor that allows you to edit the pynemo configuration file (BDY file)
+
+Boundary file generation
+------------------------
+This command line tool reads a BDY file, extracts boundary data and prepares the data for a NEMO simulation. The bdy file
+is a plain text file containing key value pairs. Please look at the sample namelists in the github repository. They are
+stored in the inputs directory. There are three different examples, they all use the same child grid but ultilise different
+data sources. One uses local data, the other uses data hosted on a THREDDS server. The last one is configured to download
+CMEMS data first and then run using the downloaded data. The namelist file shares common syntax with the NEMO simulation namelist input file.
+
+.. note:: Directory paths in bdy file can be relative or absolute.
+ The application picks the relative path from the current working
directory.
Syntax for pynemo command is
@@ -25,10 +30,11 @@ For help
::
- > pynemo -h
- > usage: pynemo [-g] -s <namelist.bdy>
+ > pynemo -h
+ > usage: pynemo [-g] -s -d <namelist.bdy>
> -g (optional) will open settings editor before extracting the data
- > -s <bdy filename> file to use
+ > -s <bdy filename> namelist file to use to generate boundary data
+ > -d <bdy filename> namelist file to use to download CMEMS data
Example comamnd
@@ -36,8 +42,43 @@ Example comamnd
> pynemo -g -s namelist.bdy
+CMEMS data download
+-------------------
+To download CMEMS data, the flag -d needs to be specified when running pynemo. This will use the specified namelist file and
+download the relevent CMEMS data. Once successful the same namelist file can be used to generate the boundary conditions by
+running PyNEMO with the -s flag. Example command.::
+
+ $ pynemo -d /PyNEMO/inputs/namelist_cmems.bdy
+
+To use the CMEMS download service an account needs to be created at http://marine.copernicus.eu/services-portfolio/access-to-products/
+Once created the user name and password need to be added to PyNEMO. To do this a file with the name CMEMS_cred.py in the utils folder
+needs to be created with two defined strings one called user and the other called pwd to define the user name and password.::
+
+ $ touch pynemo/utils/CMEMS_cred.py
+ $ vim pynemo/utils/CMEMS_cred.py
+ press i
+ user='username goes here'
+ pwd='password goes here'
+ press esc and then :wq
+
+**IMPORTANT** This will create a py file in the right place with the parameters required to download CMEMS, the password is stored as plain text so please
+do not reuse any existing password you use!
+
+The CMEMS download usage page has more information about how to configure the namelist file.
-pynemo_settings_editor
+GUI NCML Generator
+------------------
+This GUI tool facilitates the creation of a virtual dataset for input into PyNEMO. The virtual dataset is defined using NetCDF Markup Language (NcML ).
+
+Using NcML, it is possible to:
+
+- modify metadata
+- modify and restructure variables
+- combine or aggregate data from multiple datasets. The datasets may reside in the local file system or in a remote OPeNDAP (http://www.opendap.org/) server.
+
+Please see NcML generator usage page for more information in using the GUI.
+
+pynemo settings editor
----------------------
This tool will open a window where you can edit the mask and change the values of bdy parameters.
@@ -47,7 +88,7 @@ Syntax for pynemo_settings_editor command is
::
> pynemo_settings_editor [-s <bdy filename>]
-
+
.. note:: If no file name is specified then a file dialog box will open to select a file.
For help
@@ -56,9 +97,9 @@ For help
> pynemo_settings_editor -h
> usage: pynemo_settings_editor -s <namelist.bdy>
-
+
Example:
::
-
+
pynemo_settings_editor -s namelist.bdy