1 """
2 Tools for analysing the relationship between tidal stresses and tectonics on
3 icy satellites.
4
5 Written by U{Zane Selvans <http://zaneselvans.org>}
6 (C{U{zane.selvans@colorado.edu <mailto:zane.selvans@colorado.edu>}}) as part of
7 his Ph.D. dissertation research.
8
9 C{SatStress} is released under GNU General Public License (GPL) version 3. For
10 the full text of the license, see: U{http://www.gnu.org/}
11
12 The project is hosted at Google Code: U{http://code.google.com/p/satstress}
13
14 1 Installation
15 ==============
16 Hopefully getting C{SatStress} to work on your system is a relatively painless
17 process, however, the software does assume you have basic experience with the
18 Unix shell and programming within a Unix environment (though it should work on
19 Windows too). In particular, this installation information assumes you already
20 have and are able to use:
21
22 - compilers for both C and Fortran. Development has been done on Mac OS X
23 (10.5) using the GNU compilers C{gcc} and C{g77}, so those should
24 definitely work. On other systems, with other compilers, your mileage may
25 vary.
26
27 - the C{make} utility, which manages dependencies between files.
28
29 1.1 Other Required and Recommended Software
30 -------------------------------------------
31 To get the L{SatStress} package working, you'll need to install some other
32 (free) software first:
33
34 - B{Python 2.5} or later (U{http://www.python.org}). If you're running a
35 recent install of Linux, or Apple's Leopard operating system (OS X 10.5.x),
36 you already have this. Python is also available for Microsoft Windows, and
37 just about any other platform you can think of.
38
39 - B{SciPy} (U{http://www.scipy.org}), a collection of scientific libraries
40 that extend the capabilities of the Python language.
41
42 In addition, if you want to use L{GridCalc}, you'll need:
43
44 - B{netCDF} (U{http://www.unidata.ucar.edu/software/netcdf/}), a library of
45 routines for storing, retrieving, and annotating regularly gridded
46 multi-dimensional datasets. Developed by U{Unidata
47 <http://www.unidata.ucar.edu>}
48
49 - B{netcdf4-python} (U{http://code.google.com/p/netcdf4-python/}), a Python
50 interface to the netCDF library.
51
52 If you want to actually view L{GridCalc} output, you'll need a netCDF file
53 viewing program. Many commercial software packages can read netCDF files, such
54 as ESRI ArcGIS and Matlab. A simple and free reader for OS X is U{Panoply
55 <http://www.giss.nasa.gov/tools/panoply/>}, from NASA. If you want to really
56 be able to interact with the outputs from this model, you should install and
57 get familiar with:
58
59 - B{Matplotlib/Pylab} (U{http://matplotlib.sourceforge.net/}), a Matlab-like
60 interactive plotting and analysis package, which uses Python as its
61 "shell".
62
63 1.2 Building and Installing SatStress
64 -------------------------------------
65 Once you have the required software prerequisites installed, uncompress and
66 unarchive the SatStress distribution::
67
68 tar -xvzf SatStress-X.Y.Z.tar.gz
69
70 then go into the distribution directory created::
71
72 cd SatStress-X.Y.Z
73
74 To build and test the package, run::
75
76 make test
77
78 If the test cases pass, go ahead and install with::
79
80 make install
81
82 And you'll be able to write your own Python programs using the C{SatStress}
83 library.
84
85 If you're not using the GNU Fortran 77 compiler C{g77}, you'll need to edit the
86 C{Makefile} for the Love number code::
87
88 SatStress/Love/JohnWahr/Makefile
89
90 and tell it what Fortran compiler it ought to be using.
91
92 If you have any trouble getting C{SatStress} working, feel free to post to the
93 SatStress discussion board: U{http://groups.google.com/group/satstress}
94
95 2 Design Overview
96 =================
97 A few notes on the general architecture of the C{SatStress} package.
98
99 2.1 Who is the Audience?
100 ------------------------
101 In writing this software and documentation, my hope is that an undergraduate
102 research assistant who has been hired for the summer, and who has at least
103 some experience with programming (though not necessarily in Python), should
104 be able to understand how the system works, and make fruitful use of it. So
105 if it seems like things are sometimes over-explained or over-commented,
106 that's why.
107
108 2.2 A Toolkit, not a Program
109 ----------------------------
110 The C{SatStress} package is not itself a stand-alone program (or not much of
111 one anyway). Instead it is a set of tools with which you can build programs
112 that need to know about the stresses on the surface of a satellite, and how
113 they compare to tectonic features, so you can do your own hypothesizing and
114 testing.
115
116 2.3 Object Oriented
117 -------------------
118 The package attempts to make use of U{object oriented programming
119 <http://en.wikipedia.org/wiki/Object-oriented_programming>} (OOP) in order to
120 maximize the re-usability and extensibility of the code. Many scientists are
121 more familiar with the U{imperative programming style
122 <http://en.wikipedia.org/wiki/Imperative_programming>} of languages like
123 Fortran and C, but as more data analysis and hypothesis testing takes place
124 inside computers, and as many scientists become highly specialized and
125 knowledgeable software engineers (even if they don't want to admit it), the
126 advantages of OOP become significant. If the object orientation of this
127 module seems odd at first glance, don't despair, it's worth learning.
128
129 2.4 Written in Python
130 ---------------------
131 U{Python <http://www.python.org>} is a general purpose, high-level scripting
132 language. It is an interpreted language (as opposed to compiled languages
133 like Fortran or C) and so Python code is very portable, meaning it is usable
134 on a wide variety of computing platforms without any alteration. It is
135 relatively easy to learn and easy to read, and it has a very active
136 development community. It also has a large base of friendly, helpful
137 scientific users and an enormous selection of pre-existing libraries designed
138 for scientific applications. For those tasks which are particularly
139 computationally intensive, Python allows you to extend the language with code
140 written in C and Fortran. Python is also U{Free Software
141 <http://www.gnu.org/philosophy/free-sw.html>}. If you are a scientist and
142 you write code, Python is a great choice.
143
144 2.5 Open Source
145 ---------------
146 Because science today is intimately intertwined with computation, it is
147 important for researchers to share the code that their scientific results are
148 based on. No matter how elegant and accurate your derivation is, if your
149 implementation of the model in code is wrong, your results will be flawed.
150 As our models and hypotheses become more complex, our code becomes vital
151 primary source material, and it needs to be open to peer review. Opening our
152 source:
153
154 - allows bugs to be found and fixed more quickly
155 - facilitates collaboration and interoperability
156 - reduces duplicated effort
157 - enhances institutional memory
158 - encourages better software design and documentation
159
160 Of course, it also means that other people can use our code to write their
161 own scientific papers, but I{that is the fundamental nature of science}. We
162 are all "standing on the shoulders of giants". Nobody re-derives quantum
163 mechanics when they just want to do a little spectroscopy. Why should we all
164 be re-writing each others code I{ad nauseam}? Opening scientific source code
165 will ultimately increase everyone's productivity. Additionally, a great deal
166 of science is funded by the public, and our code is a major product of that
167 funding. It is unethical to make it proprietary.
168 """
169 __all__ = ["SatStress", "GridCalc",]
170 __author__ = "Zane Selvans"
171 __contact__ = "zane.selvans@colorado.edu"
172 __maintainer__ = "Zane Selvans"
173 __maintainer_email__ = "zane.selvans@colorado.edu"
174 __license__ = "http://www.gnu.org/licenses/gpl.html"
175 __docformat__ = 'epytext en'
176 __version__ = '0.1.2'
177 __projecturl__ = 'http://code.google.com/p/satstress'
178 __downloadurl__ = 'http://code.google.com/p/satstress/downloads/list'
179 __description__ = 'Tools for modeling tidal stresses and tectonics on icy satellites.'
180 __long_description__ = """
181 SatStress is a collection of objects and scripts which are useful for modeling
182 tidal stresses on icy satellites, and for comparing those stresses to mapped
183 tectonic features. It includes a Love number code which treats the satellite
184 as a Maxwell viscoelastic material. The tidal stresses currently modeled are
185 the non-synchronous rotation of a decoupled icy shell (NSR) and the radial and
186 librational tides that result from an eccentric orbit (Diurnal), as described
187 in Wahr et al. (2008).
188 """
189 __pythonrequiredversion__ = "2.5"
190
191 import datetime
192 __date__ = datetime.datetime.utcnow().ctime()
193 __copyright__ = "2007-%d %s" % (datetime.datetime.utcnow().year,__author__)
194