Getting started ¶
EarthSim supports Python 3.6 on Linux, Windows, or Mac.
EarthSim itself is a pure Python package that itself would be easy to install, but it depends on several packages (gdal, geos, and others) that are linked against binary-code geospatial libraries. Unfortunately, incompatibly compiled versions of those libraries are available from different sources, which can make it difficult to assemble an appropriate environment for safely running EarthSim. For this reason, EarthSim is currently provided via a special set of installation steps based on conda and git that ensure only a compatible set of packages is used. Specifically:
Clone the EarthSim git repository if you do not already have it:
git clone git://github.com/pyviz/EarthSim.git
Set up an environment with all of the dependencies needed to run the examples:
cd EarthSim conda create -n earthsim -c conda-forge --file=dependencies.txt conda-forge::python=3.6
Activate the earthsim environment:
for Windows; MacOS and Linux users should instead run:
source activate earthsim
earthsimmodule into this environment:
pip install -e .
Download the sample files:
These instructions are designed to build a working environment repeatably on Mac OS X, Windows, and Linux platforms, pinning dependencies to known versions to avoid incompatibilities with new releases of the software required.
Once you’ve installed EarthSim as above and are in the EarthSim directory, you can run the examples shown on the website using Jupyter :
cd earthsim-examples jupyter notebook
You should now be able to select one of the
notebooks and run it in Jupyter.
Exploring Further ¶
You can look through the User Guide and the Topics to see examples, but most of the documentation is at the sites for the packages like HoloViews that are used in the examples. A good way to get comfortable with those tools is to work through the tutorials at PyViz.org.
Assuming you are in the EarthSim directory, and the
environment is active, you can update to the latest version of
EarthSim as follows:
Get updated code and examples from git:
Update the earthsim conda environment:
conda install -c pyviz/label/earthsim -c conda-forge --file=dependencies.txt
Get a new copy of the examples to work on, and download new or updated data:
If you are actively collaborating with the EarthSim developers and want to try out the latest pyviz work as it first appears (which is not necessarily functional or stable), you can run the following after creating or updating (and activating) your earthsim environment:
conda install -c pyviz/label/dev -c conda-forge --file=dependencies-dev-overrides.txt
This command will update the main packages to the latest dev releases, which appear periodically after new features are added.
If you really want to be on the bleeding edge, you can instead get the absolute latest changes by cloning the earthsim, holoviews, geoviews, datashader, param, and panel Github repositories and running pip install -e . inside each one, pulling new changes from each of these libraries as needed. That’s what the main developers do, but it isn’t recommended for other users unless you are very skilled at debugging the broken environments that are likely to appear as packages change unpredictably over time.