Package SatStress
[frames] | no frames]

Source Code for Package SatStress

  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