Installation¶
Installing TCRM is intended to be a simple process, requiring only basic understanding of command line operations. TCRM has been installed and tested on a range of unix-based systems, Windows and Mac OS/X systems.
Downloading¶
The TCRM code can be downloaded from the Geoscience Australia GitHub page.
For users wanting to only run the code, a zip file or gzipped tar file of the latest releases can be downloaded from the Releases page.
Those wanting to contribute to development can fork the repository. Submit a pull request to have your changes integrated into TCRM.
Dependencies¶
TCRM relies on a number of additional libraries that are not part of the standard library. There are several ways to obtain the required libraries – using Python’s recommended tool pip, installing a distribution such as Python(x,y) package (for Windows environments) or Anaconda (cross-platform), or installing the libraries from source or binary installers (pre-compiled binary Windows installer versions for all the libraries (both 32-bit and 64-bit) can be obtained here).
For detailed instructions on installation of these dependencies, please see the documentation for each individual library.
Python - v3.5 or later
Numpy - v1.6 or later
Scipy - v0.12 or later
Matplotlib v1.2 or later.
netcdf4-python - version 1.0.8 or later
Shapely - v1.2.15 or later
Parallel execution in multi-processor environments (with MPI installed) requires mpi4py
Using pip¶
If you have pip installed, the required modules can be installed using the following command, executed in the main TCRM directory
pip -v install -r requirements.txt
This will automatically build the required libraries (listed in the
requirements.txt
file) and any dependencies. pip
must be on
the $PATH
for this to work.
Using Anaconda¶
To install tcrm
, make a new environment:
conda env create -f tcrmenv.yml
After creating the environment the user needs to move to that environment using the command
conda activate tcrm
The bash promt will look like
(tcrm) user@server:~/tcrm$
Setting the environment¶
To enable TCRM to run correctly, you may need to change some
environment settings. The important variable to set is the
PYTHONPATH
variable. This should be set to the path where you have
extracted the contents of the zip file. In the examples below, change
/path/to/tcrm
to the location where you extracted the TCRM files.
A complete discussion on environment variables in Python is given in the Python documentation.
Windows¶
The Python documentation contains some simple instructions for setting environment variables on Windows systems here. See this link for setting the variables on different Windows systems.
BASH shell¶
export PYTHONPATH=$PYTHONPATH:/path/to/tcrm:/path/to/tcrm/Utilities
CSH/TCSH shell¶
setenv PYTHONPATH $PYTHONPATH:/path/to/tcrm:/path/to/tcrm/Utilities
Dependencies¶
TCRM relies on a number of additional libraries that are not part of the standard library. There are several ways to obtain the required libraries – using Python’s recommended tool pip, installing a distribution such as Python(x,y) package (for Windows environments) or Anaconda (cross-platform), or installing the libraries from source or binary installers (pre-compiled binary Windows installer versions for all the libraries (both 32-bit and 64-bit) can be obtained here).
For detailed instructions on installation of these dependencies, please see the documentation for each individual library.
Python - v3.5 or later
Numpy - v1.6 or later
Scipy - v0.12 or later
Matplotlib v1.2 or later.
netcdf4-python - version 1.0.8 or later
Shapely - v1.2.15 or later
Parallel execution in multi-processor environments (with MPI installed) requires mpi4py
Using pip¶
If you have pip installed, the required modules can be installed using the following command, executed in the main TCRM directory
pip -v install -r requirements.txt
This will automatically build the required libraries (listed in the
requirements.txt
file) and any dependencies. pip
must be on
the $PATH
for this to work.
Using Anaconda¶
To install tcrm
, make a new environment:
conda env create -f tcrmenv.yml
After creating the environment the user needs to move to that environment using the command
conda activate tcrm
The bash promt will look like
(tcrm) user@server:~/tcrm$
Windows¶
For Windows users, the code includes the compile.cmd
script in the
main TCRM diretory that will build these extensions in place. By
default, TCRM uses the MinGW suite (http://www.mingw.org) for
compiling the extensions. Other Windows-based packages can also be
used (e.g. Cygwin). See the Python documentation on writing
configuration files for the distutils
package for more details.
Notes¶
It is recommended to use a stand-alone Python installation for
compiling and running TCRM. Installations linked to other software
such as ArcGIS have resulted in compilation errors, as the required
numpy
libraries are pre-compiled and packaged with such
installations.
Testing the installation¶
The model code includes a suite of unit tests that ensure elements of the code base will work as expected, even if a user makes modificaitons to the code.
The test suite can be run from the main directory. On Windows, run the
run_test_all.cmd
script from the main TCRM directory. On Unix, use
the command
python ./tests/run.py
This should report no errors or failures.
Special note for Windows systems¶
On a Windows system, tests.test_files.testModulePath()
may fail
due to the different path separators (/
versus \\
) used by the
Windows system. This test failure will appear as:
======================================================================
FAIL: testModulePath (tests.test_files.TestModuleUtilities)
Test flModulePath returns correct path, base & extension
----------------------------------------------------------------------
Traceback (most recent call last):
File "tcrm\tests\test_files.py", line 22, in testModulePath
self.assertEqual(self.path, p)
AssertionError: 'tcrm/tests' != 'tcrm\\tests'
----------------------------------------------------------------------
Ran 111 tests in 92.513s
FAILED (failures=1)
Such an error will not affect model execution.
Using Docker¶
As an alternative way to install TCRM, you can use Docker. Docker is a very convenient way to run containerized software which avoids all the hassle with compilation or dependencies.
Prerequisites¶
Install Docker Community Edition for your system.
Test the installation¶
Run this command
docker run olivierdalang/tcrm nosetests --exe
The first time, this will take some time, as it needs to download the docker image.
If it works, you should see (after some time), something like OK (SKIP=1)
.
If not, you would see something like FAILED (SKIP=1, errors=1)
.
Normal usage¶
To run TCRM though Docker, you need to mount a folders containing your inputs and the output folder in the container.
This can be done like this (assuming you have a my_conf.ini file in a folder)
docker run -v /path_to/my_data_folder:/home/src/mount -v /path_to/my_output_folder:/home/src/output olivierdalang/tcrm python tcevent.py -v -c mount/my_conf.ini
Replace /path_to/my_data_folder
and /path_to/my_output_folder
by the folders you want to use on your system, and python tcevent.py
v -c example/yasi.ini
by the TCRM command you want to use.
The first time, the docker image will have to be downloaded which will take some time.
Developement¶
You can also use Docker when developping TCRM by mounting the source
git checkout https://github.com/GeoscienceAustralia/tcrm.git
cd tcrm
docker run -v ${PWD}:/home/src olivierdalang/tcrm python tcevent.py -c example/yasi.ini
If you wish to make changes to the builds steps or dependencies, you need to rebuild the image locally
docker build -t olivierdalang/tcrm .
Releases¶
For users to be able to use the docker image out of the box without having to rebuild it locally, the image must be pushed to the docker hub repository like this
docker build -t olivierdalang/tcrm .
docker login
docker push olivierdalang/tcrm
This can be setup to be done automatically after pushes through docker hub.