=== INSTRUCTIONS TO RUN THE MODELS == 0. INDEX 1. Directory contents 2. Compiling models 3. To run the programs 4. General organization and format of the codes 5. Convergence criteria 6. The climate model 6.1 Inputs 6.2 Outputs 6.3 Tunning the code 7. The photochemical model 7.1 Boundary conditions 7.2 Inputs 7.3 Outputs 8. The coupled mode 9. To use a new star flux 1. DIRECTORY CONTENTS * Files: couple.f - Main program to run the climate or the photochemical model or both couple.q - Unix commands useful if you want to run the programs using always the same input inputexample.dat - Example of the input for couple.f make_couple_sun - make file to compile the models * The most important subdirectories in the directory CHEMCLIM are: CLIMA - Contains the files for the climate model ATMCHEM - Contains the files for the photochemical model AUX: Contains programs that normalized and bin the star flux of a given star to be used as input in the climate and photochemcial models * Other subdirectories are: COUPLE - Contains the fortran files that are used to couple the climate and photochemical codes. COUPLE.o - Storage the *.o files created during the compilation of the codes in coupled mode. DATA - Contains the fluxes of the stars ready to be used by the photochemical and climate models. FLUX - Fortran programs that read the fluxes of the stars for the climate and photochemical code. INCLUDECOUP - Include files for the couple mode. Common blocks and parameters. IO - Input and output files for the models 2. COMPILING THE MODELS It is necessary to compile all the files, even if you are only using one model. If you want to avoid this, feel free to modify the make file. IMPORTANT: The options in the make file: -xtarget=ultra -xarch=v9, are system dependent. Find out if they work on your Sun system, otherwise you will create a executable file that won't be executable. To compile the models, type: make -f make_couple_sun The executable file 'couple' will be created The subroutine CLIMA/RRTM/k_g.f takes about an hour to compile, the time depends on your system. Be patient. 3. TO RUN THE PROGRAMS These are your options: a) Type: ./couple Answer the questions that will come out b) Type: ./couple < inputfile For this option there is a file that can be used as an example called inputexample.dat IMPORTANT: Before running the programs be sure that you have selected all the correct inputs. Read the following sections to find out where the relevant files are stored. 4. GENERAL ORGANIZATION AND FORMAT OF THE CODES With the exception of this readme file all the files are written in lower case and all the subdirectories are written in capital letters. Almost all the common files and parameters are in files that are read in the programs using the INCLUDE command. The files are in the subdirectories: INCLUDECOUP ATMCHEM/INCLUDECHEM CLIMA/INCLUDECLIM The only exceptions are the common files shared by RRTM and clima.f and all the RRTM programs. The files containing parameters have been named: parNAMEOFTHEPARAMETER.inc If the file contains more than one parameter, let's say N1 and N2, then it is named: parN1_N2.inc The files containing common blocks are named: comNAMEOFTHECOMMONBLOCK.inc Only one common block is included on each file. The subdirectory file names are intended to be the most descriptive using a minimum of letters. For example, PRTCL stands for 'particle', and that means this subdirectory contains the subroutines that deal with particles. The subdirectories called DATA have files that must not be modified, because they have constant data used by the models. Given that the programs are divided in several subdirectories, the unix command grep is useful to search variables in the programs. To search for STRING in the subdirectories write: grep STRING ../* 5. CONVERGENCE CRITERIA * Coupled mode: The program will stop once it reaches convergence or tell you when it need more iterations between the 2 models to converge. * Climate model: Convergence has to be checked by eye. The parameters that tell you if the program has converged are DIVF and DT(ND). More details in the description of the main output of this code (sec. 6.2) * Photochemical model: This code can be tricky when checking convergence. It will stop once it converges but it can stop for other reasons. Check carefully the file: CHEMCLIM/ATMCHEM/atm_chem.out_explained.pdf Both programs have adjustable time steps. That is if the solutions of the step N is similar to the N-1 they increment the time step. The time steps in the photochemical code change by orders of magnitud. This is one of the indicators that the program is converging. The climate model will increment its time step up to a maximum time step allowed. Very big time steps in the climate model may produce numerical problems 6. THE CLIMATE MODEL This is a 1-D radiative-convective model. The infrared scheme, RRTM is useful for high-O2 atmospheres, i.e. ones not too different from present Earth. Gives good results for atmospheres with up to 100 times the present value of CO2 and 100 times the present value of CH4. You can choose between 2 different energy conservation modes: 1. Non-strict (ICONSERV = 0): This method does not conserve energy on each step. The program converges faster and works great for high-O2 atmospheres. 2. Strict conservation (ICONSERV= 1): Recommended for high-CO2 atmospheres, it conserves energy on every time step. WARNING! In some instances, we get significantly different answers using the two different values of ICONSERV, even though both time-stepping methods converge to radiative equilibrium in the stratosphere and a moist adiabatic lapse rate in the convective troposphere. The differences appear to result from changes in the efficiency with which energy is deposited in the upper troposphere. Moral of this story: The implementation of different parameterizations of moist convection can make a difference. Be aware of this! 6.1 INPUTS * CHEMCLIM/IO/input_clima.dat - Contains some more options for the program, the file contains the explanation of each one. * CHEMCLIM/IO/mixing_ratios.dat - Composition of the atmosphere in volume mixing ratios (Ar, CH4, CO2, O2), the layer of the tropopause and the O3 column depth (only useful for the coupled mode) * CHEMCLIM/IO/CLIMA/TempIn.dat - Initial temperature and water profile used when IUP =0 (see input_clima.dat for definition of IUP). For the coupled model the stratospheric water comes from the photochemical model. IMPORTANT: The input file is overwritten at the end of one run of the climate model, so the next time you run the climate model you will start form the latest solution. If you want to save a given initial profile copy TempIn.dat to another file. * CHEMCLIM/IO/fromPhoto2Clima.dat - Used only in the coupled mode. Contains the water and ozone profiles generated by the photochemical model. * couple.f - This program contains the time variables (units =seconds): DTC, dtmax and TSTOP. They usually don't need to be modified. TSTOP is only used in the strict energy conservation mode. DTC is translated to dt0 in the climate model and it is the starting time step dtmax is the maximum time step allowed. 6.2 OUTPUTS * fromClima2Photo.dat - Temperature and water to be used in the photochemical model when run in coupled mode. * clima_allout.tab - This file is very important to check the convergence of the program. It contains the fluxes, temperature, heating rates and water profiles calculated by the program from the first to the last step. The first 3 and the last 3 runs are written in detail. For the coupled mode case it contains information of the LAST iteration between the 2 models. This are the variables contained in the file: J = Number of the layer (1 is the top of the atmosphere) P = Pressure (atm)at the temperature grid points, i.e., the midpoints of the layers (plus the ground) ALT = Altitude (km) T = Temperature calculated at the end of this step (K) CONV = Tags for convective layers (non-zero values indicate convective layers) DT = T - TOLD TOLD = Temperature from the previous iteration FH2O = Water mixing ratio at the new time step TCOOL = Cooling rate (degrees/day) THEAT = Heating rate (degrees/day) PF = Pressure at the flux grid points, i.e., the layer boundaries FTOTAL = Total flux (ergs/cm^2/s) FTIR = Total IR flux FDNIR = Downward IR flux FUPIR = Upward IR flux FTSOL = Total solar flux (visible/nearIR) FDNSOL = Downward solar flux FUPSOL = Upward solar flux DIVF = total flux / IR flux For the rest of the runs the following quantities are listed: NST = iteration number JCONV = Number of the last convective layer CHG = Maximum relative change between the temperature (at any layer) calculated at the step NST and the step NST-1. It is used to set the time step. dt0 = time step in seconds DIVF(1) = total flux / IR flux at the top of the atmosphere. The smaller the number better the convergence. DIVF(1) < 1e-2 is usually acceptable, < 1e-3 is very good. DT(ND) = Difference between the temperatures at the surface calculated at the step NST-1 and NST. Smaller the number (<1e-2), better the solution. TN(ND)= Surface temperature calculated at the end of the step NST 6.3 TUNING THE CODE The model should reproduce the US standard atmosphere when simulating present Earth. In order to do that the surface albedo (SRFALB in input_clima.dat) is fixed so we get ~288 K at the surface. For the coupled mode, SRFALB = 0.2; for stand alone, SRFALB =0.207 NOTE: All of these values are higher than the actual surface albedo of the Earth. This is because the model, as configured here, does not explicitly include clouds. Think of the cloud layer as being at the surface. The calculated planetary (TOA) albedo for this model is less than the actual planetary albedo, which compensates for the lack of greenhouse warming by the clouds. 7. THE PHOTOCHEMICAL MODEL It is a 1-D model that includes the effects of rainout and lightning. It works for high O2-low CH4-low CO2 atmospheres. There is another photochemical model for high CO2 atmospheres posted on the Virtual Planetary Laboratory website. 7.1 BOUNDARY CONDITIONS The boundary conditions are included as DATA in the main directory of the photochemical model CHEMCLIM/ATMCHEM/atm_chem.f Check them out to be sure that you are running the case you want. 7.2 INPUTS * CHEMCLIM/IO/input_atmchem.dat - Contains some more options for the program, the file contains the explanation of each one. * CHEMCLIM/IO/fromClima2Photo.dat - Temperature and water profiles generated by the climate model when run in coupled mode. * CHEMCLIM/IO/mixing_ratios.dat - Composition of the atmosphere in volume mixing ratios (Ar, CH4, CO2, O2), the layer of the tropopause and the O3 column depth (only useful for the coupled mode). IMPORTANT: This file is overwritten at the end of each run, so the program will start from the last solution. * CHEMCLIM/ATMCHEM/IO/atm_composition.dat - Contains the atmospheric chemistry to start the model. IMPORTANT: This file is overwritten at the end of each run, so the program will start from the latest solution. * CHEMCLIM/ATMCHEM/IO/planet.dat - Data for a given planet. IMPORTANT: This program has never been tried for non-Earth-sized planets, the gravity constant and the surface pressure may not be transferred to all the subroutines. * couple.f - Time variables (in seconds) are in the main code: DTP is the starting time step that will be adjusted with in the photochemical code on each iteration until it reaches the maximum time allowed, TSTOP. 7.3 OUTPUTS * CHEMCLIM/IO/outchem.dat - It contains ALL the relevant quantities that the photochemical model can produce. On this file you can check out the convergence of the program. Its contents and the convergence criteria are explained in the file: * CHEMCLIM/ATMCHEM/atm_chem.out_explained.pdf * CHEMCLIM/IO/fromPhoto2Clima.dat - Used only in the coupled mode. Contains the water and ozone profiles to be used by the climate model. 8. THE COUPLED MODE The program couple.f contains the subroutines necessary to detect when the climate and photochemical models have converged when they are in COUPLED mode. The program will stop when it reaches convergence or will tell you when needs more iterations between the 2 models to reach convergence. The time variables TIMEC and TIME store the physical time that each program takes in one run (that is the sum of all time steps). They are not used now but can be used to transfer the time transpired in the climate model to the photochemical model and vice versa. Note that you will need to implement the necessary changes in couple.f for that. Time dependency makes no sense when the climate model runs with the option ICONSERV=0 because one needs to conserve energy at each time step. The output file CHEMCLIM/IO/output_couple.dat will contain the quantities relevant to the convergence criteria and the most important results of both programs, these are: Ozone column depth Volume mixing ratios of H2O, H2,CH4,CO, N2O and CH3Cl Number densities of OH and O3 Stellar flux at the top of the atmosphere and flux at the surface of the planet Pressure, altitude, and temperature profile 9. TO USE A NEW STAR FLUX If you want to use a star other than the ones given here you will need a high resolution spectrum of the star. Once you have it, use the programs CHEMCLIM/AUX/spectra_clima.f and CHEMCLIM/AUX/spectra_photo.f to generate the files that can be read be the codes. You will need to change some parameters within the spectra*.f files. Open them and check them out before using them. Once you have the output files with the binned spectrum moved them to CHEMCLIM/DATA. You will need to add that option in the subroutines contained in CHEMCLIM/FLUX. Created by Antigona Segura January, 2007