PLANETS : formation and evolution of giant planets
This project is intensively based on 'Cesam2k' developed by P. Morel at Observatoire de la Côte d'Azur (Nice, France; http://www.oca.eu/morel/).
This project is also based on the work of T. Guillot and his code 'Cepam'.
Developed by T. Guillot (OCA, France) and M. Havel (OCA, France).
Contributions also provided by M. Ikoma (TITech, Japon), and I. Genda (TITech, Japon)
Contacts : mathieu.havel@…, guillot@…
Project creation date (dd/mm/yyyy) : 22/01/2008
Last update from 'Cesam2k' : 30/05/2009 (v3.2.12)
Project current version : 0.3.16 (14/09/2009)
Directory structure
PLANETS |-SConstruct -- builder script for PLANETS |-README |-Changelog -- self explaining name |-UPDATES -- trace back for all updates applied from 'Cesam2k' |-VERSION -- version number and date of PLANETS source code |-+-bin | |- ** all binaries files (executables) ** |-+-doc | |---Cesam2k | | |- ** all documentation of 'Cesam2k' ** (to be removed in future) | |---Planets | | |- ** all documentation of PLANETS ** |-+-exploit | |- SConscript -- builder script for building exploit programs (calibration, des...) | |- ** exploitation directory - some programs to exploit results from PLANETS ** |-+-lib | |- ** all built libraries (.a) ** |-+-modules | |- ** all .mod files built while compiling ** |-+-run | |- ** run directory - you may run PLANETS with proper configuration files here ** |-+-source | |- ** all fortran source files (.f) ** |-+-SUN_STAR_DATA | |-SConscript -- builder script for building opacity/EOS data programs | |-+-EOS | | |- ** all data/configuration files concerning equation of state ** | |-+-HOUDEK | | |- ** all fortran source file to compile opacity tables program ** | | |-+-alex05 | | | |- ** all data files to build 'alex05' opacity tables ** | | |-+-alex94 | | | |- ** all data files to build 'alex94' opacity tables ** | | |-+-opal05 | | | |- ** all data files to build 'opal05' opacity tables ** | | |-+-opal95 | | | |- ** all data files to build 'opal95' opacity tables ** | | |-+-lib | | | |- ** all source files (.f) to build 'libopint.a' | |- ** some data files concerning equation of state ('Cesam2K' ones), and some compressed opacity tables ** |-+-tests | |-SConscript -- builder script for testing programs of PLANETS (invoked by main SConstruct file) | |- ** all test source codes ** |-+-tools (usage : sed -f script_name -i file_name) | |-README -- describe all scripts | |-space.sed -- convert 'Cesam2k' code into compatible 'gfortran' one, and remove trailing white space and | | tabulations at the end of lines. | |-precision_k.sed -- change each non-commented (and not preceed by "double" keyword) occurrences | | of "precision" to "precision_k", because "precision" is a reserved keyword in FORTRAN.
Dependencies
In order to compile and run PLANETS you'll need following programs (depending on your OS system)
"W" means Windows, "L" means Linux, and "M" means MacOS). Recommended versions are put in "[]".
"*" means necessary program or library
"o" means optional program or library
W M L program or library name Download
- python [2.6.4] http://www.python.org/download/
o o o pgplot [5.2.2] see libGrWin (for Windows only) * * * gfortran [4.4.1] http://quatramaran.ens.fr/~coudert/gfortran/gfortran-windows.exe
or http://gcc.gnu.org/wiki/GFortranBinaries (for Windows only) or ifort [11.1.059] http://www.intel.com/cd/software/products/asmo-na/eng/219771.htm (for Linux only) or lf95
- scons [1.2.0] http://www.scons.org/download.php
- MinGW http://sourceforge.net/project/showfiles.php?group_id=2435
- libGrWin [lGrWn0999be-MinGW] http://spdg1.sci.shizuoka.ac.jp/grwinlib/english/download.html
o o o tar+gzip+bzip2 http://gnuwin32.sourceforge.net/downlinks/libarchive.php (for Windows only) o o o pysvn [1.7.0] http://pysvn.tigris.org/project_downloads.html o o o subversion [1.6.5] http://subversion.tigris.org/project_packages.html ----------------------------------------------------------------------------------------------------------------
INFO : If you want to build tar compressed (Gzip or Bzip2) archive (see Archive Creation), you'll need Tar + Gzip + Bzip2
INFO : If you want to contribute to PLANETS, you'll need "pysvn" and "subversion" (SVN)
INFO : If you want to plot results during evolution, you'll need "PGPLOT"
Installation procedure
Under Windows (XP or Vista)
Follow the steps in that order to be able to use PLANETS :
- Download : "gfortran", "MinGW", "python", "scons", and "libGrWin". (see above)
- Install "gfortran" (there should be no problem, because installer update automatically Windows PATH variable so that Windows know the command "gfortran").
- Install "python". You can choose the default install location, ie. "C:\Python25".
- Install "scons". The installer should find Python installation directory.
- Install "MinGW" using the automatic installer. Choose downloading default programs + g77 + Objective C compiler. You can choose the default install location, ie. "C:\MinGW".
- Install "libGrWin". You can choose the default install location, ie. "C:\GrWin". The installer should find the MinGW installation directory. Choose installing the default programs, ie. "GrWin", "Calcomp", and "pgplot".
- [OPTIONAL] Install "libarchive". You can choose the default install location and options, ie. "C:\Program Files\!GnuWin32". This package is needed to create archives of the project.
- [OPTIONAL] Install "subversion". You can choose the default install location and options, ie. "C:\Program Files\Subversion". This package is needed to get a versionned oode, work with "subversion" (SVN), and be able to contribute to PLANETS.
- [OPTIONAL] Install "pysvn". You can choose the default install location and options. This package is needed to use "subversion" (SVN) with the PLANETS builder tool.
- Change the (user) PATH variable of Windows.To do so, you can both launch 'regedit' (and choose : HKEY_CURRENT_USER -> Environment) or right click on (Desktop ->) "My computer" -> "Advanced" tab -> "Environment variables" button. Please, note that only user variables will be edited.
- Modify (create it if not present) the "PATH" variable :
- PATH = "...;C:\Python25;C:\MinGW\bin;C:\Python25\Scripts"
- PATH = "...;C:\Program Files\!GnuWin32\bin", if you installed "libarchive"
- PATH = "...;C:\Program Files\Subversion\bin", if you installed "svn"
- PATH = "...;C:\Program Files\gfortran\bin", if you installed "gfortran"
- Add the "PGPLOT_FONT" variable, adding the path to "grfont.dat"; eg. : PGPLOT_FONT = "C:\GrWin\pgpglot\grfont.dat"
- Modify (create it if not present) the "PATH" variable :
- In the source PLANETS' directory, copy "des_m.f.win" in "des_m.f", and "des_r.f.win" in "des_r.f".
- You may want to change some parameters in the 'SConstruct' file : win_*=, FC=, *_flags=, install_dir= ; see in-file for details. Default parameters should work perfectly.
- To compile, just open "cmd.exe" ("Start" -> "Execute" -> "cmd"), and go in PLANETS directory (eg. cd C:\Documents and Settings\USER\Desktop\Planets) and follow instruction in section "PLANETS' compilation : builder tool" below.
WARNING : in SConstruct file, it is advised (for Windows user only) to write windows specific paths with "
" (double backslash) instead of "\" (single backslash); eg : "C:
MinGW
bin" instead of "C:\MinGW\bin"
WARNING : "pysvn" do not work with "Python25" 64 bits version. So if you plan to use "pysvn", install 32 bits version of "Python25"
Under Linux
- After having installed all needed programs, go in PLANETS' directory.
- Please, consider to install "pysvn" and "svn" if you want to contribute to PLANETS.
- You may want to change some parameters in the 'SConstruct' file : lin_*=, FC=, *_flags=, install_dir= ; see in-file for details. Default parameters should work perfectly.
Under MacOSX
Should be very similar to Linux case...
Compilation : the builder tool
- Open a terminal (cmd.exe under Windows), and go in PLANETS' directory.
- For the first compilation, simply type :
scons install
All the project should be built, but you still need to build opacity tables (see Opticity Tables)
- For next compilation, you just need to type :
scons
- Additional compilation parameters can be used :
scons -h -- display PLANETS project help (give you all commands available for PLANETS)
scons -H -- display scons general help
scons -j 2 -- build project using 2 processors (parallel build)
scons -c -- clean built files
- By default, PLANETS builder tool retrieve files from cache when it is possible (ie. if cache exist and if source file has not changed).
- By default, PLANETS builder tool do not recompile unmodified files : it is controlled by MD5 sum and not by timestamp as in Makefile. This behaviour can be changed with "Decider" functions of the SConstruct file; see in-file for details.
Opacity tables
Before using PLANETS, you have to extract the file "SUN_STAR_DATA/opa_yveline.data.gz", and then run 'ascii2bin_opa' (created with 'scons install' command) in order to build "yveline opacity tables" (answer "o", "opa_yveline.data", and "opa_yveline.bin")
To build HOUDEK opacity tables, just type :
scons opacity=1
Archive creation
To create an archive (you need "libarchive" to be installed under Windows), just type :
scons archive=1
This will create the file "planets_vXX.YY.ZZ_dd-mm-yyyy.tar.bz2" (where XX.YY.ZZ is the version number, and dd-mm-yyyy is the date) in "archives" directory
The following directories and files will be archived :
- dir. "doc"
- dir. "exploit"
- dir. "run"
- dir. "source"
- dir. "SUN_STAR_DATA"
- dir. "tests"
- dir. "tools"
- file "SConstruct"
- file "README"
- file "VERSION"
- file "Changelog"
PGPLOT library
If you do not have PGPLOT library installed on your system, PLANETS provide a fake PGPLOT interface (set of subroutines that do nothing) so that the code will compile and run without any problems. Just use option "nopgplot=1" at scons call time (scons -h for details).
Contributing to PLANETS
The PLANETS builder tool can manage versions of the code (both in human way and subversion one). To contribute to PLANETS you'll need to use this tool to commit your change, which depend on "subversion" (SVN) and "pysvn". Of course you can commit your changes using only SVN without using the builder tool, but doing so, the "human version system" will not be used.
To get the versionned code (type in a terminal) :
svn co https://svn.oca.eu/codes/PLANETS/trunk Planets
Human version of PLANETS is of kind : XX.YY.ZZ
- XX = major version number (increment this number mean that PLANETS will not be compatible with previous major releases)
- YY = release version number (increment this number mean that PLANETS just included significant changes and improvements : models...)
- ZZ = minor version number (increment this number mean that PLANETS just included minor changes : text, small bugs...)
So you have the choice between these two ways to commit your changes :
- scons upver=ACTION
will do the job automatically (managing all needed option like log messages, human version...). See "RELEASE specific help" of scons -h.
- scons svn=ACTION OPTIONS
give you more control on log messages, name of created directory... See "SVN specific help" of scons -h)
In addition to let you commit your changes, the builder tool allow you to :
- update : get last changes committed by other users
- getrev : get a specified SVN version of PLANETS
- create branches, tags... see the builder tool help (scons -h)
Sometimes you need to add/remove a file/directory from the project. To do so, you need to use the "svn" action
- scons svn=add name=file/directory
- scons svn=rm name=file/directory
Finally, when you work on a tagged version (got from https://svn.oca.eu/codes/PLANETS/tags/TAG-VERSION), you cannot commit your change using the builder tool, to avoid corrupting a released version. In that case, you need to switch in the good directory :
(see Subversion help for conflicting files).