Skip to content
This repository was archived by the owner on May 23, 2022. It is now read-only.

Commit eaa31df

Browse files
author
Romain Beucher
committed
Add some information to the README
Update Readme and documentation Fix link Change section on Underworld/UWGeodynamics in the Readme
1 parent 9ff0035 commit eaa31df

File tree

5 files changed

+312
-8
lines changed

5 files changed

+312
-8
lines changed

‎README.rst

+230-8
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ Underworld Geodynamics project
2222

2323
.. image:: https://github.com/underworldcode/UWGeodynamics/blob/development/tutorials/images/Tutorial1.gif
2424

25+
.. image:: https://github.com/underworldcode/UWGeodynamics/blob/development/docs/source/img/collision_wedge.gif
26+
2527
The UWGeodynamics module facilitates prototyping of geodynamics models using Underworld.
2628
It can be seen as a set of high-level functions within the Underworld ecosystem.
2729
It is a means to quickly get the user into Underworld modelling and assumes very
@@ -45,11 +47,229 @@ possibilities offered by Underworld.
4547

4648
.. image:: /docs/source/img/SandboxCompression.gif
4749

48-
Getting started
49-
---------------
50+
UWGeodynamics and Underworld
51+
----------------------------
52+
53+
*UWGeodynamics* uses the Underworld_ Application Programming Interface (API).
54+
Both projects are supported by The Underworld development team led by Louis Moresi and based in Melbourne, Australia
55+
at the University of Melbourne and at Monash University.
56+
57+
*Underworld* and *UWGeodynamics* both provide powerful tools to develop numerical geodynamic models.
58+
But their approaches are different: *UWGeodynamics* largely guides users into a way of doing things.
59+
The Underworld API provides a series of tools and components (Mesh, Mesh variables, system of equations, functions)
60+
and leaves the responsibility to arrange those components to the user. The main advantage of the Underworld API is its flexibility.
61+
The main inconvenient resides in a somewhat steeper learning curve. *UWGeodynamics* components are
62+
designed to be more natural to non-experimented numerical modellers or people with little knowledge in programming.
63+
It is a way to quickly get started and design numerical models. Developing complex models can also be facilitated
64+
by the *UWGeodynamics* high-level interface as it requires less time and less involvement
65+
with the details of the Underworld API.
66+
67+
The two approaches are complementary and mixing the two approaches is possible and highly encouraged.
68+
69+
Note on versioning
70+
------------------
71+
72+
Since version 1.0 The Underworld development team has decided to match the *UWGeodynamics* version number with
73+
the latest supported version of Underworld.
74+
UWGeodynamics v2.7 is then supporing Underworld up to version 2.7.
75+
76+
The third number is used for *UWGeodynamics* only (v2.7.1, v2.7.2 etc.)
77+
78+
The development branch is based on the current *Underworld* development branch.
79+
80+
The Current release (**DOI** citable):
81+
82+
`DOI <https://zenodo.org/badge/114189389.svg)](https://zenodo.org/badge/latestdoi/114189389>`_
83+
84+
Quick Start / Testing
85+
----------------------
86+
87+
We provide a docker container via binder_.
88+
This is a quick solution to get you started and run the examples and tutorials
89+
without installing anything on your machine. That is a good way to see if the
90+
software can actually be useful to you.
91+
The ressource are however limited and you should not try to run model with high resolution.
92+
3D models can not be run in the binder.
93+
94+
Where to find documentation?
95+
----------------------------
5096

5197
The full documentation is available on `ReadTheDocs <http://uwgeodynamics.readthedocs.org/>`_
5298

99+
Additional documentation and function specific documentation can be find in the python doctrings.
100+
You can acces them in the Jupyter_ notebook by prepending or appending the method, variable or function with ``?``.
101+
102+
Installation
103+
-------------
104+
105+
Docker_ installation
106+
~~~~~~~~~~~~~~~~~~~~
107+
108+
Docker containers provide and easy-way to set up and distribute
109+
applications. They also provide a safe and consistent environment which
110+
facilitate debugging and reproducibility of models. The image we provide
111+
contains all the dependencies and configuration files required to run
112+
Underworld models. Users can start developping model as soon as they
113+
have downloaded the image, independently of the operating system running
114+
on their machine.
115+
116+
We strongly encourage users to run UWGeodynamics using the docker images
117+
we provide on `Docker Hub`_
118+
119+
Different version of the `underworldcode/uwgeodynamics` image can be
120+
pulled using a tag:
121+
122+
1. The *latest* tag points to the github master branch and uses the latest
123+
*underworld* release.
124+
2. The *dev* tag points to the github development and uses the development
125+
branch of *underworld*.
126+
3. release tags such as *v2.7.1* points to a specific version.
127+
128+
**Command line**
129+
130+
Once you have installed docker on your system you can *pull* the
131+
*UWGeodynamics* official image as follow:
132+
133+
.. code:: bash
134+
135+
docker pull underworldcode/uwgeodynamics
136+
137+
You can list all the images available on your system as follow:
138+
139+
.. code:: bash
140+
141+
docker images
142+
143+
An image can be deleted as follow:
144+
145+
.. code:: bash
146+
147+
docker rmi underworldcode/uwgeodynamics
148+
149+
You can then start a docker container. (An instance of
150+
an image).
151+
152+
.. code:: bash
153+
154+
docker run -d \
155+
--name my_container \
156+
-p 8888:8888 \
157+
--mount source=myvol,target=/workspace/user-data \
158+
underworldcode/uwgeodynamics
159+
160+
You can access the container via your browser at the following
161+
address: http://localhost:8888
162+
163+
It is also possible to ssh into the container as follow:
164+
165+
.. code:: bash
166+
167+
docker exec -it my_container /bin/bash
168+
169+
You can list the containers currently existing on your machine by running:
170+
171+
.. code:: bash
172+
173+
docker ps -a
174+
175+
The "a" means "all container". The :code:`docker ps` command only list
176+
running containers.
177+
178+
Docker containers can be stop (so that they do not use CPU or RAM ressource):
179+
180+
.. code:: bash
181+
182+
docker stop my_container
183+
184+
They can also be deleted:
185+
186+
.. code:: bash
187+
188+
docker rm my_container
189+
190+
.. warning::
191+
192+
It's a good idea to keep track of how many containers have been created as
193+
they can rapidly take a lot of space on your machine.
194+
195+
Kitematic_
196+
~~~~~~~~~~
197+
198+
Kitematic_ is a program that provides a graphical user interface to
199+
the *docker* daemon and to Docker Hub.
200+
The software is available for Windows, MacOsx and Linux. Be aware that on
201+
linux the installation may differ depending on the distribution you
202+
are running.
203+
204+
1. Download and Install Kitematic_
205+
2. Open Kitematic and search for the **uwgeodynamics** image.
206+
3. Create a container by clicking on the create button.
207+
208+
You should now have a container appearing on the left side of your
209+
kitematic window. The first thing to do now is to create a link between
210+
a local directory (A directory on your physical hard drive) and a volume
211+
directory inside the docker container. A volume is a special directory
212+
that can be accessed from outside the container. It is the location you
213+
will use to save your results.
214+
215+
Local Installation
216+
~~~~~~~~~~~~~~~~~~~~
217+
218+
This is not recommended and involves installing *Underworld* and all
219+
its dependencies. Docker is highly recommended!!!
220+
221+
**Requirements**
222+
223+
- Python >= 2.7
224+
- A Working version of Underworld2 >=2.6.0 (Please refer to the
225+
Underworld documentation)
226+
- pint >= 0.8
227+
228+
.. note::
229+
The bleeding edge version of *Underworld* (development branch)
230+
is now python 3 compatible only.
231+
*UWGeodynamics* is python 3 ready and can thus be used with it.
232+
233+
**Install**
234+
235+
**from Pip**
236+
237+
The UWGeodynamics module can be installed directly from the Python
238+
Package Index:
239+
240+
.. code:: bash
241+
242+
pip install UWGeodynamics
243+
244+
**from sources**
245+
246+
The module source files are available through github_
247+
248+
.. code:: bash
249+
250+
git clone https://github.com/underworldcode/UWGeodynamics.git
251+
252+
It can then be installed globally on your system using
253+
254+
.. code:: bash
255+
256+
pip install UWGeodynamics/
257+
258+
259+
Seeking Support?
260+
----------------
261+
262+
Error messages are useful to understand the source of a problem.
263+
264+
If you cannot solve the problem by yourself you can ask for help by creating an
265+
issue on GitHub. If the problem if specific to your model you may be ask to continue the conversation
266+
through email.
267+
268+
*UWGeodynamics* is an open source free software and we cannot guarantee that it
269+
is free of bugs. Feel free to signal any strange behaviour by raising an issue (see below section
270+
on how to contribute.)
271+
272+
53273
Contributing
54274
------------
55275

@@ -120,10 +340,12 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY
120340

121341
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <http://www.gnu.org/licenses/lgpl-3.0.en.html>.
122342

123-
Versioning
124-
----------
125-
126-
Current releases (**DOI** citable):
127-
128-
`DOI <https://zenodo.org/badge/114189389.svg)](https://zenodo.org/badge/latestdoi/114189389>`_
129343

344+
.. _binder: https://mybinder.org/v2/gh/rbeucher/UWGeodynamics-binder/master
345+
.. _Underworld: https://github.com/underworldcode/underworld2
346+
.. _Jupyter: http://jupyter.org/
347+
.. _Docker: https://www.docker.com
348+
.. _Docker Hub: https://hub.docker.com/r/underworldcode/uwgeodynamics
349+
.. _Kitematic: https://kitematic.com/
350+
.. _github: https://github.com/underworldcode/UWGeodynamics.git
351+
.. _Pint: https://pint.readthedocs.io/en/latest

‎docs/source/Installation.rst

+37
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,18 @@ Once you have installed docker on your system you can *pull* the
3434
3535
docker pull underworldcode/uwgeodynamics
3636
37+
You can list all the images available on your system as follow:
38+
39+
.. code:: bash
40+
41+
docker images
42+
43+
An image can be deleted as follow:
44+
45+
.. code:: bash
46+
47+
docker rmi underworldcode/uwgeodynamics
48+
3749
You can then start a docker container. (An instance of
3850
an image).
3951

@@ -55,6 +67,31 @@ It is also possible to ssh into the container as follow:
5567
5668
docker exec -it my_container /bin/bash
5769
70+
You can list the containers currently existing on your machine by running:
71+
72+
.. code:: bash
73+
74+
docker ps -a
75+
76+
The "a" means "all container". The :code:`docker ps` command only list
77+
running containers.
78+
79+
Docker containers can be stop (so that they do not use CPU or RAM ressource):
80+
81+
.. code:: bash
82+
83+
docker stop my_container
84+
85+
They can also be deleted:
86+
87+
.. code:: bash
88+
89+
docker rm my_container
90+
91+
.. warning::
92+
93+
It's a good idea to keep track of how many containers have been created as
94+
they can rapidly take a lot of space on your machine.
5895

5996
Kitematic_
6097
~~~~~~~~~~

‎docs/source/img/collision_wedge.gif

9.37 MB
Loading

‎docs/source/index.rst

+42
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ Welcome to UWGeodynamics's documentation!
33

44
.. image:: ./img/Tutorial1.gif
55

6+
.. image:: ./img/collision_wedge.gif
7+
68
The UWGeodynamics module intents to facilitate rapid prototyping of geodynamics
79
models using Underworld. It can be seen as a set of high-level functions within
810
the Underworld ecosystem. It is a means to quickly get the user into Underworld
@@ -26,6 +28,46 @@ We hope that the user will naturally move to the low-level functionalities as
2628
he or her gets more confident, and by doing so will access the wide range
2729
of possibilities offered by Underworld.
2830

31+
UWGeodynamics and Underworld
32+
----------------------------
33+
34+
*UWGeodynamics* uses the *Underworld_* Application Programming Interface (API).
35+
Both projects are supported by The Underworld development team led by Louis Moresi and based in Melbourne, Australia
36+
at the University of Melbourne and at Monash University.
37+
38+
*Underworld* and *UWGeodynamics* both provide powerful tools to develop numerical geodynamic models.
39+
But their approaches are different: *UWGeodynamics* largely guides users into a way of doing things.
40+
The Underworld API provides a series of tools and components (Mesh, Mesh variables, system of equations, functions)
41+
and leaves the responsibility to arrange those components to the user. The main advantage of the Underworld API is its flexibility.
42+
The main inconvenient resides in a somewhat steeper learning curve. *UWGeodynamics* components are
43+
designed to be more natural to non-experimented numerical modellers or people with little knowledge in programming.
44+
It is a way to quickly get started and design numerical models. Developing complex models can also be facilitated
45+
by the *UWGeodynamics* high-level interface as it requires less time and less involvement
46+
with the details of the Underworld API.
47+
48+
The two approaches are complementary and mixing the two approaches is possible and highly encouraged.
49+
50+
Versioning
51+
------------------
52+
53+
Since version 1.0 The Underworld development team has decided to match the *UWGeodynamics* version number with
54+
the latest supported version of Underworld.
55+
UWGeodynamics v2.7 is then supporing Underworld up to version 2.7.
56+
57+
The third number is used for *UWGeodynamics* only (v2.7.1, v2.7.2 etc.)
58+
59+
The development branch is based on the current *Underworld* development branch.
60+
61+
Quick Start / Testing
62+
----------------------
63+
64+
We provide a docker container via binder_.
65+
This is a quick solution to get you started and run the examples and tutorials
66+
without installing anything on your machine. That is a good way to see if the
67+
software can actually be useful to you.
68+
The ressource are however limited and you should not try to run model with high resolution.
69+
3D models can not be run in the binder.
70+
2971
.. image:: ./img/SandboxCompression.gif
3072

3173
.. toctree::

‎joss/paper.md

+3
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ UWGeo comes with a series of examples, benchmarks and tutorials setups that can
119119
be used as cookbook recipes. They also provide a wide range of teaching materials
120120
useful to introduce numerical geodynamic modeling to students.
121121

122+
New functionalities are constantly added to the code and contributions are more than
123+
welcomed. You can access the full documentation online at https://uwgeodynamics.readthedocs.io
124+
122125
# Audience
123126

124127
The module is directed towards a large audience, including earth-science

0 commit comments

Comments
 (0)