PyARTS: an ARTS related Python package ====================================== :Author: Cory Davis .. contents:: Introduction ------------ PyARTS is a python package, which has been developed to compliment the Atmospheric Radiative Transfer System - ARTS (http://www.sat.uni-bremen.de/arts/). Although ARTS is very flexible software, it's primary function currently is to perform radiative transfer simulations for a given atmospheric state. PyARTS simplifies the process of creating these atmospheric scenarios, and also provides a front-end to the ARTS software for convenient configuration and execution of ARTS radiative transfer calculations. PyARTS includes two high-level modules that provide most of the functionality needed for the preparation and execution of ARTS simulations: clouds produces arbitrarily complex multi-phase multi-habit cloud fields for arts simulations. This includes the generation of single scattering properties of non-spherical ice particles and the generation of particle number density fields for given ice and liquid water content fields. *clouds* also provides convenience functions for producing simple 1D and 3D box cloud scenarios. arts (formally called PyARTS) contains classes and functions that actually perform ARTS simulations. The ArtsRun class provides general functionality for configuring, performing, and managing the output of ARTS simulations. There are several lower-level modules that, as well as serving the arts and cloud modules, are also useful in their own right: arts_scat provides functions and classes for the calculation of single scattering properties of ice and liquid water hydrometeors using the *T*-matrix method arts_types provides support for the manipulation, loading, and saving in ARTS XML format of some ARTS classes, e.g, ArrayOfGriddedField3, GriddedField3. artsXML provides general XML input and output that can be used for all ARTS objects. arts_math provides several interpolation, quadrature, and grid creation functions. general a general purpose module that includes simplified pickling/unpickling functions for saving arbitrarily complex python objects, and functions for performing multi-threaded calculations. What is currently missing. -------------------------- Gas absorption lookup table generation The one thing that is required by ARTS that cannot yet be provided by PyARTS is the lookup tables for gaseous absorption coefficients. It is planned to include this capability at some point. In the meantime, if you have MATLAB license, the Atmlab package, described at http://www.sat.uni-bremen.de/arts/tools.php, does provide this functionality. An example ---------- Here is a simple example python session that demonstrates what can be done with the PyARTS package. In this case we perform 3D polarized radiative transfer in an atmosphere containing a uniform box shaped cloud. :: [cory@fog cory]$ python Python 2.3.4 (#1, Sep 2 2004, 16:32:38) [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-5)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from PyARTS import clouds >>> from PyARTS import artsXML >>> from PyARTS import arts_math >>> from PyARTS import arts >>> from PyARTS import general Start by defining a simple box shaped cloud filled with horizontally aligned oblate spheroids. >>> a_cloud=clouds.boxcloud(ztopkm=14.0,zbottomkm=13.0,lat1=-2.0,lat2=2.0, ... lon1=-2.0,lon2=2.0,cb_size={'np':5,'nlat':5,'nlon':5}, ... zfile='PyARTS/data/tropical.z.xml',tfile='PyARTS/data/tropical.t.xml', ... IWC=0.1) >>> horizontal_plate=clouds.Crystal(ptype=30,NP=-1,aspect_ratio=2.0) >>> a_cloud.addHydrometeor(horizontal_plate) Generate single scattering data files, and particle number density fields. >>> a_cloud.scat_file_gen(f_grid=[500e9,503e9],num_proc=2) >>> a_cloud.pnd_field_gen('pnd_field.xml') Generate grids for ARTS RT simulation >>> p_grid=arts_math.gridmerge(arts_math.nlogspace(101325.0,0.1,100), ... a_cloud.p_grid[1:-2]) >>> artsXML.saveTensor(p_grid,'p_grid.xml') >>> lat_grid=arts_math.gridmerge(arts_math.nlinspace(-16.0,16.0,100), ... a_cloud.lat_grid[1:-2]) >>> artsXML.saveTensor(lat_grid,'lat_grid.xml') >>> lon_grid=lat_grid >>> artsXML.saveTensor(lon_grid,'lon_grid.xml') Now define parameters for ARTS run, giving the Monte Carlo algorithm a maximum execution time of 10 seconds (you can also specify a desired accuracy or a fixed number of iterations) >>> arts_params={ ... "atm_basename":"PyARTS/data/tropical", ... "cloud_box":a_cloud.cloudbox, ... 'freq':501.18e9, ... "gas_species":["ClO","O3","H2O,H2O-MPM89","N2-SelfContStandardType"], ... "gas_abs_lookup":"PyARTS/data/gas_abs_lookup.xml", ... "lat_grid":"lat_grid.xml", ... "lon_grid":"lon_grid.xml", ... "max_time":10, ... "p_grid":"p_grid.xml", ... "pnd_field_raw":a_cloud.pnd_file, ... "rte_pos":{'r_or_z':95000.1,'lat':9.1,'lon':0}, ... "rte_los":{'za':99.14,'aa':180}, ... "scat_data_file":a_cloud.scat_files, ... "stokes_dim":4 ... } And perform RT calculations (using 2 processors)... >>> my_run=arts.ArtsRun(arts_params,'montecarlo','cfile.arts') >>> my_run.run_parallel(2) And here is the simulated Stokes vector... >>> print 'Simulated Stokes vector =\n'+str(my_run.y) Simulated Stokes vector = [ 1.17613500e+02 5.57757000e+00 -7.19482500e-02 -2.69899500e-01] >>> print 'standard error = '+str(my_run.error) standard error = [ 1.66664512 1.23597316 0.4771547 0.43988175] Prerequisites ------------- * Python 2.?, (you will probably have this already) * Numeric Python * A fortran compiler * f2py * scipy-distutils: this is also available from the f2py site. Download -------- The package is available via anonymous CVS from the ARTS web-site. To check out the package, follow the instructions given at http://www.sat.uni-bremen.de/arts/download.php, but give "PyARTS" instead of "arts" as the module name. Installation ------------ Once you have all of the above prerequisites installed, and checked out PyARTS from the ARTS cvs repository, run the following from the base directory. python setup.py install --home=~ This will install the package in ~/lib/python and also it will but some scripts in ~/bin. If you omit the --home argument python will try and install the modules in the standard 3rd party location (something like /usr/lib/python2.2/site-packages), which obviously wont happen unless you have superuser privileges In most cases the install command above will work, however, if like me, your Numeric package is not installed in the standard place (something like /usr/lib/python2.x/site-packages/Numeric), you need to use a slightly different command to build and install PyARTS: python setup.py build_src build_ext --include-dirs=/include/python install --home=~ Once installed you should modify your PYTHONPATH environment variable to include the installation directory (eg ~/lib/python). Fortran compilers and quad precision ************************************ I have successfully built this package with the following compilers * g77 * lf95 The PyARTS package includes the quad precision versions of Mishchenko's T-matrix code, which roughly doubles the range of convergent particle size parameters. If you have a fortran compiler, such as lf95, that supports quad precision, you can include the quad precision functions by typing (for a Bourne shell) before installing. export HAVE_QUAD=1 If you have more than one compiler there are extra command line arguments in the setup.py program that you can use to specify which one is used. For details please consult the f2py documentation. A shell script laheybuild.sh is included in the distribution to indicate how this is done for lf95. Optional NAG enhancements to the T-matrix code ********************************************** As in the original T-matrix code by Mishchenko, performance can be significantly improved in some cases by using a optional set of NAG algorithms. This requires a NAG site license. If you have a NAG site-license you should obtain the file ampld2.f, place it in the src directory of the PyARTS distribution, and type export HAVE_NAG=1 before performing the installation steps described above. Testing your Installation ------------------------- There are several unit tests in the test/ folder of the distribution. These test both both the functionality and accuracy of the software. To run them all, and check that your installation is OK, type python testall.py -v If you would like to contribute to PyARTS, which is definitely encouraged, it is strongly recommended that the above command is run, and that all tests are successful, before committing your changes to CVS. Examples -------- Some example scripts are provided in the examples/ folder. These all should work as they only depend on data provided in the data/ folder. The testall.py script described above actually verifies that the examples run without error. At the time of writing the examples are: get_atm_fields.py A demonstration of the artsGetAtmFields function MCwith3Dboxcloud.py Creates a simple cloudy-sky scenario and performs a single radiative transfer calculation using the ARTS-MC module. Documentation ------------- Most modules in the package have reasonably complete docstring documentation. To view this do the following: /pydoc.py -p 1234 and open http://localhost:1234 in your web browser. There is an arts_scat.py user guide in the doc/ folder of the distribution