Installing PCSE¶
Requirements and dependencies¶
PCSE is being developed on Ubuntu Linux 14.04 and Windows 7 using Python 2.7.11 and is known to work with
the 3.x series (using the 2to3 tool). As Python is a platform independent language, PCSE
works equally well on Linux, Windows or Mac OSX.
Before installing PCSE, Python itself must be installed on your system. Most Linux systems provide
Python through the native package manager. For Windows users the most straightforward approach for installing
Python is through one of the prepackaged Python distributions such as Enthought Canopy,
Anaconda or PythonXY. The advantage of the prepackaged distributions is that they provide a working
version of Numpy out-of-the-box which can be difficult to install on Windows. Mac OSX users can most easily
install Python and Numpy using HomeBrew, i.e brew install Python Numpy
.
The dependencies of PCSE are the following:
- Numpy >= 1.6
- SQLalchemy >= 0.8
- PyYAML >= 3.11
- tabulate >= 0.7.5
- xlrd >= 0.9.3
- xlwt >= 1.0.0
Setting up your python environment¶
A convenient way to set up your python environment for PCSE is through the Anaconda python distribution. In the present PCSE Documentation all examples of installing and using PCSE refer to Windows 7 platform.
First, we suggest you download and install the MiniConda python distribution which provides a minimum
python environment that we will use to bootstrap a dedicated virtual environment for PCSE. For the rest
of this guide we will assume that you use Windows 7 and install the
32bit miniconda for python 3 (Miniconda3-latest-Windows-x86.exe
). The virtual enviroment that
we will create contains not only the dependencies for PCSE, it also includes many other useful packages
such as IPython Pandas and the Jupyter notebook. These packages will be used in the Getting Started section
as well.
After installing MiniConda you should open a command box and check that conda is installed properly:
C:\>conda info
Current conda install:
platform : win-32
conda version : 4.0.5
conda-build version : not installed
python version : 3.5.1.final.0
requests version : 2.9.1
root environment : C:\Miniconda3 (writable)
default environment : C:\Miniconda3
envs directories : C:\Miniconda3\envs
package cache : C:\Miniconda3\pkgs
channel URLs : https://repo.continuum.io/pkgs/free/win-32/
https://repo.continuum.io/pkgs/free/noarch/
https://repo.continuum.io/pkgs/pro/win-32/
https://repo.continuum.io/pkgs/pro/noarch/
config file : None
is foreign system : False
Now we will use a Conda environment file to recreate the python environment that we use to develop and run
PCSE. First you should download the conda environment file which comes in two flavours, a bare minimum
environment for running PCSE (downloads/py2_pcse.yml
) and a more complete environment which
includes the Jupyter notebook, Pandas and IPython (downloads/py2_pcse_full.yml
). If you intend
to run the ‘Getting started’ section, you should take the latter one. Save the environment file
on a temporary location such as d:\temp\make_env\
. We will now create a dedicated virtual environment
using the command conda env create
and tell conda to use the environment file with the option -f p2_pcse_full.yml
as show below:
D:\temp\make_env>conda env create -f py2_pcse_full.yml
Fetching package metadata: ....
.Solving package specifications: .........
Linking packages ...
[ COMPLETE ]|##################################################| 100%
Requirement already satisfied (use --upgrade to upgrade): backports.ssl-match-hostname==3.4.0.2 in c:\miniconda3\envs\py2_pcse_b\lib\site-packages
Requirement already satisfied (use --upgrade to upgrade): line-profiler==1.0 in c:\miniconda3\envs\py2_pcse_b\lib\site-packages
Requirement already satisfied (use --upgrade to upgrade): sphinx-rtd-theme==0.1.7 in c:\miniconda3\envs\py2_pcse_b\lib\site-packages
Collecting tabulate==0.7.5
Installing collected packages: tabulate
Successfully installed tabulate-0.7.5
#
# To activate this environment, use:
# > activate py2_pcse
#
You can then activate your environment (note the addition of [py2_pcse]
on your command prompt) and
run an upgrade to upgrade all packages to the latest versions:
D:\temp\make_env>activate py2_pcse
Deactivating environment "C:\Miniconda3"...
Activating environment "C:\Miniconda3\envs\py2_pcse"...
[py2_pcse] D:\temp\make_env>conda upgrade --all
Fetching package metadata: ....
Solving package specifications: .........
Package plan for installation in environment C:\Miniconda3\envs\py2_pcse:
The following packages will be downloaded:
package | build
---------------------------|-----------------
vs2008_runtime-9.00.30729.1| 1 1.1 MB
zlib-1.2.8 | vc9_3 95 KB
... Lots of output here
Proceed ([y]/n)? y
Fetching packages ...
vs2008_runtime 100% |###############################| Time: 0:00:02 518.43 kB/s
... Lots of output here
pyqt-4.11.4-py 100% |###############################| Time: 0:00:04 571.51 kB/s
tornado-4.3-py 100% |###############################| Time: 0:00:01 387.81 kB/s
Extracting packages ...
[ COMPLETE ]|##################################################| 100%
Unlinking packages ...
[ COMPLETE ]|##################################################| 100%
Linking packages ...
1 file(s) copied.###################################### | 81%
[ COMPLETE ]|##################################################| 100%
[py2_pcse] D:\temp\make_env>
Installing and testing PCSE¶
The easiest way to install PCSE is through the python package index (PyPI). Installing from PyPI is mostly useful if you are interested in using the functionality provided by PCSE in your own scripts, but are not interested in modifying or contributing to PCSE itself. Installing from PyPI is done using the package installer pip which searches the python package index for a package, downloads and installs it into your python environment:
[py2_pcse] D:\temp\make_env>pip install PCSE
Collecting PCSE
Requirement already satisfied (use --upgrade to upgrade): numpy>=1.6.0 in c:\miniconda3\envs\py2_pcse\lib\site-packages (from PCSE)
Requirement already satisfied (use --upgrade to upgrade): xlrd>0.9.0 in c:\miniconda3\envs\py2_pcse\lib\site-packages (from PCSE)
Requirement already satisfied (use --upgrade to upgrade): tabulate>=0.7.0 in c:\miniconda3\envs\py2_pcse\lib\site-packages (from PCSE)
Requirement already satisfied (use --upgrade to upgrade): SQLAlchemy>=0.8.0 in c:\miniconda3\envs\py2_pcse\lib\site-packages (from PCSE)
Installing collected packages: PCSE
Successfully installed PCSE-5.2
If you are wondering what the difference between pip and conda are than have a look here
If you want to develop with or contribute to PCSE, than you should fork the PCSE repository on GitHub and get a local copy of PCSE using git clone. See the help on github and for Windows/Mac users the GitHub Desktop application.
To guarantee its integrity, the PCSE package includes a number of self tests that test individual components as well as the entire simulation. These tests verify that the output produced by the different components matches with the expected outputs. Test data for the individual components can be found in the pcse.tests.test_data package, while the test data for the entire chain is stored in an SQLite database (pcse.db). This database can be found under .pcse in your home folder and will be automatically created when importing PCSE for the first time. When you delete the database file manually it will be recreated next time you import PCSE.
For testing the PCSE package we need to start python and import pcse:
[py2_pcse] D:\temp\make_env>python
Python 2.7.11 |Continuum Analytics, Inc.| (default, Mar 4 2016, 15:18:41) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
Anaconda is brought to you by Continuum Analytics.
Please check out: http://continuum.io/thanks and https://anaconda.org
>>> import pcse
Building PCSE demo database at: C:\Users\wit015\.pcse\pcse.db
>>>
Next, the tests can be executed by calling the test() function at the top of the package:
>>> pcse.test()
runTest (pcse.tests.test_abioticdamage.Test_FROSTOL) ... ok
runTest (pcse.tests.test_assimilation.Test_WOFOST_Assimilation) ... ok
runTest (pcse.tests.test_partitioning.Test_DVS_Partitioning) ... ok
runTest (pcse.tests.test_evapotranspiration.Test_PotentialEvapotranspiration) ... ok
runTest (pcse.tests.test_evapotranspiration.Test_WaterLimitedEvapotranspiration1) ... ok
runTest (pcse.tests.test_evapotranspiration.Test_WaterLimitedEvapotranspiration2) ... ok
runTest (pcse.tests.test_respiration.Test_WOFOSTMaintenanceRespiration) ... ok
runTest (pcse.tests.test_penmanmonteith.Test_PenmanMonteith1) ... ok
runTest (pcse.tests.test_penmanmonteith.Test_PenmanMonteith2) ... ok
runTest (pcse.tests.test_penmanmonteith.Test_PenmanMonteith3) ... ok
runTest (pcse.tests.test_penmanmonteith.Test_PenmanMonteith4) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager1) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager2) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager3) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager4) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager5) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager6) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager7) ... ok
runTest (pcse.tests.test_agromanager.TestAgroManager8) ... ok
runTest (pcse.tests.test_wofost.TestPotentialSunflower) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedWinterWheat) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedSunflower) ... ok
runTest (pcse.tests.test_wofost.TestPotentialPotato) ... ok
runTest (pcse.tests.test_wofost.TestPotentialWinterWheat) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedSpringBarley) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedGrainMaize) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedWinterRapeseed) ... ok
runTest (pcse.tests.test_wofost.TestPotentialWinterRapeseed) ... ok
runTest (pcse.tests.test_wofost.TestWaterlimitedPotato) ... ok
runTest (pcse.tests.test_wofost.TestPotentialSpringBarley) ... ok
runTest (pcse.tests.test_wofost.TestPotentialGrainMaize) ... ok
runTest (pcse.tests.test_lintul3.TestLINTUL3_SpringWheat) ... ok
runTest (pcse.tests.test_wofost_npk.TestWOFOSTNPK_WinterWheat) ... ok
----------------------------------------------------------------------
Ran 33 tests in 57.472s
OK
If the model output matches the expected output the test will report ‘OK’, otherwise an error will be produced with a detailed traceback on where the problem occurred. Note that the results may deviate from the output above because one or more tests may have been temporarily disabled (skipped) often due to problems with the test.
Moreover, SQLAlchemy may complain with a warning that can be safely ignored:
/usr/lib/python2.7/dist-packages/sqlalchemy/types.py:307: SAWarning:
Dialect sqlite+pysqlite does *not* support Decimal objects natively, and
SQLAlchemy must convert from floating point - rounding errors and other
issues may occur. Please consider storing Decimal numbers as strings or
integers on this platform for lossless storage.
d[coltype] = rp = d['impl'].result_processor(dialect, coltype)