The Art of Climate Modeling

Community Atmosphere Model

Tutorial

Dani Bundy Coleman

Online DocumentationCAM Homepage:

http://www.ccsm.ucar.edu/models/atm-cam

• Running CAM in CCSM• User’s Guide• Scientific Description• Control Simulations

Tutorial Overview

I. Prepare new case

II. Modify code: make ice clouds transparent to longwave radiation

III. Plot results

I. Prepare new case (Summary)

A) Create new case (if this was done yesterday, skip to next item)

1) create_newcase

2) edit env_conf

3) configure and build

4) standard run settings: queue, project number, wall clock

B) Modify input to CAM to get daily average history files

1) where to add CAM namelist variables

2) namelist variables

a) nhtfrq

b) mfilt

1.A.1: create_newcase b30.ACMatm1Fully coupled CCSM3 Low Resolution Model

Case name = b30.ACMatm1

Hybrid run: like b30.hyb from yesterday's tutorial.

Create new case% cd /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/scripts

% create_newcase -case /home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1 -res T31_gx3v5 -mach bluesky -compset B -ccsmroot /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19

Successfully added env_mach.bluesky to /home/bluesky/bundy/scripts/b30.ACMatm1

Successfully created new case root directory /home/bluesky/bundy/scripts/b30.ACMatm1

I.A.2: edit env_conf• Build: this might have been done yesterday% cd /home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1

% ls

SourceMods/ env.readme env_mach.bluesky*

configure* env_conf env_run

• Edit env_confsetenv RUN_TYPE hybrid

setenv RUN_REFCASE b30.031

setenv RUN_REFDATE 0400-01-01

• Check it your hybrid run from yesterday % diff -b env_conf /home/bluesky/$USER/ccsm3/scripts/b30.hyb/env_conf

< setenv CASE b30.ACMatm1

< setenv CASESTR b30.ACMatm1

---

> setenv CASE b30.hyb

> setenv CASESTR b30.hyb

I.A.3: configure and build

% configure -mach bluesky

Generating resolved setup namelist-prestage and build scripts

and installing build scripts for libraries

See directory /home/bluesky/bundy/ccsm3/scripts/b30.ACMatm1/Buildexe/

See directory /home/bluesky/bundy/ccsm3/scripts/b30.ACMatm1/Buildnml_Prestage/

...

% b30.ACMatm1.bluesky.build &-------------------------------------------------------------------------

Preparing T31_gx3v5 component models for execution

-------------------------------------------------------------------------

... (this will take several minutes)

Meanwhile, edit run scripts (next page)

1.A.4: edit env_run with standard changesEdit env_run for a five day run with daily outputsetenv SETBLD AUTO

setenv STOP_OPTION ndays

setenv STOP_N 5setenv HIST_OPTION daily

setenv AVHIST_OPTION daily

Edit for queing system: b30.ACMatm1.bluesky.run # @ wall_clock_limit = 600 (600 seconds = 10 mins, twice as long as we anticipate)

# @ class = ded1_rg8

# @ account_no = 54040010

Edit for archiving: env_mach.blueskysetenv DOUT_L_MSPRJ 54040010

setenv DOUT_L_MS TRUE

Edit for archiving: b30.ACMatm1.bluesky.l_archive# @ account_no = 54040010

(see documentation in CCSM User's Guide:)

I.B.1: Input to the CAM: namelist

The CAM (unfortunately) doesn't get HIST_OPTION from env_run.

The default history file from CAM is a monthly average, so we need to tell CAM we want daily averages.

Standard input to CAM uses a namelist.To modify the namelist, edit:Buildnml_Prestage/cam.buildnml_prestage.csh

I.B.2: modify the CAM namelist Modify

$CASEROOT/Buildnml_Prestage/cam.buildnml_prestage.csh

cat >! atm.stdin << EOF

&camexp

caseid = '$CASE'

...

divdampn = 0

nhtfrq(1) = -24

mfilt(1) = 1

/

EOF

In the next few tutorials, you'll learn how to make this change for

the other component models. Today we'll just look at atmosphere

history files.

<= Add new lines anywhere after &camexp

<= …and anywhere before “/”

I.B.2.a: namelist variable nhtfrq

To change to the default history file to daily average output, we set the namelist variable:

nhtfrq(1) = -24nhtfrq = history tape frequency (of writing out)(1) = the first history file (h0). You can have up to 6

files.-24 = every 24 hours

CAM User's Guide: nhtfrqIf NHTFRQ(1)=0, the file will be a monthly average. Only the first file series

may be a monthly average. If NHTFRQ(i)$ >$0, frequency is input as number of timesteps. If NHTFRQ(i)$ <$0, frequency is input as number of hours.

I.B.2.b: namelist variable mfilt

To specify that we want one time sample on each history file, we set the namelist variable:

mfilt(1) = 1

mfilt = number of time samples on history file

(1) = the first history file (h0). You can have up to 6 files.

CAM User's Guide: mfilt

Array of number of time samples to write to each history files series (a time sample is the history output from a given timestep)

II. Modify code (Summary)

A)Science of the project

B)Find the source code

C)Modify the source code

D)Build and run

II.A: Science of the project

• Ice clouds are a strong regulator of

infrared radiation

• We're going to make “ice” clouds in

CAM transparent to this longwave

radiation

– Anticipated impact of this change on the

atmosphere?

II.B. Find the source code

1) Translating science into source code

2)Tools for searching CAM source code

3)Deciding which file(s) to modify

II.B.1: Translating science to source code

• Search in CAM Scientific Description for “longwave radiation”

4.9 Parameterization of Longwave RadiationThe method employed in the CAM 3.0 to represent longwave radiative transfer is

based on an absorptivity/emissivity formulation

• This gives us a clue of what to look for in the code. If we find

where the emissivity is calculated and/or used, we can modify

it to make ice clouds transparent to longwave radiation.

II.B.2: Tools to search CAM code

• UNIX commands find and grep can do the job, and these

suffice for the other component models

• CAM source code is in a complicated directory structure, so

we have a script which uses find and grep within this structure

• These scripts are in your path; if you want to use them in the

future, copy them to your home machine before leaving NCAR

a)grepccm: search text in all files in the directory structure

b) findccm: find a file in the directory structure

II.B.2.a: grepccm

• When CAM builds, it creates a file called Filepath in the build directory.

% ls /ptmp/$USER/b30.ACMatm1/atm/obj/Filepath

• Filepath is a list of all the directories containing source code

For example:/home/bluesky/bundy/ccsm3/scripts/b30.ACMatm1/SourceMods/src.cam

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/dynamics/eul

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/advection/slt

...

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/csm_share/cpl

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/utils/timing

• grepccm looks in each file in each directory listed in Filepath

• You must be in a directory containing Filepath to use this tool

% cd /ptmp/$USER/b30.ACMatm1/atm/obj

% grepccm "cloud emissivity"

II.B.3.a: Deciding which file to modify:

interpreting grepccm output

• examining output

• addfld/outfld calls imply this is

the end of calculations of this

field (for this timestep)

• intent(out)

implies the field is calculated

in a subroutine in the file

param_cldoptics.F90

% grepccm "cloud emissivity" ---- searching /ptmp/bundy/b30.ACMatm1/atm/obj

9 other directories

---- searching /home/bluesky/bundy/ccsm3/scripts/b30.ACMatm1/SourceMods/src.cam

No match.

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/dynamics/eul

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/advection/slt

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/control

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/mathutil

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/physics

icarus_scops.F90: ' error = stratiform cloud emissivity less than zero'

...

param_cldoptics.F90: call addfld ('EMIS', '1', pver, 'A','cloud emissivity' ,phys_decomp)

param_cldoptics.F90: real(r8), intent(out) :: emis (pcols,pver) ! cloud emissivity

param_cldoptics.F90:! Cloud emissivity.

pkg_cldoptics.F90:! Compute cloud emissivity using cloud liquid water path (g/m**2)

pkg_cldoptics.F90: real(r8), intent(out) :: emis(pcols,pver) ! cloud emissivity (fraction)

radclwmx.F90:! assumes randomly overlapped clouds with variable cloud emissivity to

radclwmx.F90: real(r8), intent(in) :: emis(pcols,pver) ! Cloud emissivity

radctl.F90: real(r8), intent(in) :: emis(pcols,pver) ! Cloud emissivity

---- searching /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/csm_share/shr

II.B.3.b: Look at a promising file

• Look at one of the promising files: param_cldoptics.F90

(use less, more or your favorite editor)% less /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/physics/param_cldoptics.F90

• Find the line we saw in the grepccm output

and look to see how emis is used.

L65 subroutine param_cldoptics_calc(state, cldn, ...

...

L90 real(r8), intent(out) :: emis (pcols,pver) ! cloud emissivity

! Cloud emissivity.

call cldems(lchnk, ncol, cwp, ficemr, rei, emis)

! Effective cloud cover

do k=1,pver

do i=1,ncol

effcld(i,k) = cldn(i,k)*emis(i,k)

end do

end do

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/physics/param_cldoptics.F90

II.B.3.c: Decide which lines to modify

• emis is calculated in the call to cldems and is then used to calculate the effective cloud

• We want to make our change right before the effective cloud

calculation

II.C. Modify source code

1) Copy the file from collections to case directory

2) Identify where temperature is below freezing

Are these really ice clouds?

3) Set emissivity = 0

4) Add a diagnostic field to the history file to see

emissivity before and after the modifications

II.C.1: Copy the file to local dir

• The CCSM build will look for source code in user modified

directories

– SourceMod contains directories for each component model% ls /home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1/SourceModssrc.cam/ src.cpl/ src.datm/ src.dlnd/ src.latm/ src.xatm/ src.xlnd/src.clm/ src.csim/ src.dice/ src.docn/ src.pop/ src.xice/ src.xocn/

• Copy the file to SourceMods/src.cam % cd /home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1/SourceMods/src.cam/

% cp /fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/physics/param_cldoptics.F90

/home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1/SourceMods/src.cam/

• Open the file in an editor and go to “call cldems” (near line 160)% xemacs param_cldoptics.F90

II.C.2: Set emis=0 where t .lt. 0

• If the temperature is below freezing, make the cloud transparent

by setting emissivity = 0 (In SourceMods/src.cam/param_cldoptics.F90)

• Make the change here; the following two pages explain how you

would figure out that state%t is the temperature in degrees K

! Cloud emissivity.

call cldems(lchnk, ncol, cwp, ficemr, rei, emis)

! Effective cloud cover do k=1,pver do i=1,ncol if ( state%t(i,k) .lt. 273._r8 ) then emis(i,k) = 0._r8 endif effcld(i,k) = cldn(i,k)*emis(i,k) end do end do

•. k=1,pver loops over the vertical coordinate

•i = 1,ncol loops over the horizontal (lat/lon) coordinate

•_r8 is a floating point number with a precision particular to the CAM build. Declare all floating point variables as real(r8) and use _r8 after all decimal points.

II.C.3: Find temperature

• The state variables, including temperature, are in a user defined

type call physics_state, defined in the file physics_types.F90

• Use findccm in the same way as we did grepccm to find this file % cd /ptmp/$USER/b30.ACMatm1/atm/obj

% findccm physics_types.F90

9 directories

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/models/atm/cam/src/

physics

This is the directory containing physics_types.F90

• Look at the file (we don't need to edit it, so we can leave it in the

collections directory)

/fis/cgd/cseg/csm/collections/ccsm3_0_1_beta19/ models/atm/cam/src/physics/physics_types.F90

type physics_state integer :: & lchnk, &! chunk index ncol ! number of active columns real(r8), dimension(pcols) :: & ps, &! surface pressure phis ! surface geopotential real(r8), dimension(pcols,pver) :: & t, &! temperature (K) u, &! zonal wind (m/s) v, &! meridional wind (m/s) s, &! dry static energy omega, &! vertical pressure velocity (Pa/s) pmid, &! midpoint pressure (Pa) pdel, &! layer thickness (Pa) rpdel, &! reciprocal of layer thickness (Pa) lnpmid, &! ln(pmid) exner, &! inverse exner function w.r.t. surface... zm ! geopotential height above surface at midpoints (m)

<= Temperature

units = K

II.C.3: temperature in physics_state

II.C.4: add a field to history file: outfld

• To check that our modification behaves as we expect it to, write out emis

before and after we change it.

• We know the emissivity is already available on the history files because

there is a call to outfld in this subroutine. This occurs after the

modification we added.

call outfld('EMIS' ,emis , pcols,lchnk)

• To write out emissivity before we change it, copy this line to a location above

the change and modify the name that will appear on the history file. The

outfld subroutine works on the entire array, so make the call before the

do-loops. ! Cloud emissivity.

call cldems(lchnk, ncol, cwp, ficemr, rei, emis) call outfld('EMISstd' ,emis , pcols,lchnk)! Effective cloud cover do k=1,pver do i=1,ncol

if ( state%t(i,k) .lt. 273._r8 ) then

II.C.4: add a field to history file: addfld

• We need to tell the model a little more about the field we are

writing out.

• During initialization, we call the subroutine addfld. Look for the

addfld call for EMIS earlier in this file (line 51, subroutine

param_cldoptics_init)

• Copy and paste the addfld call. Modify the name of the field from

EMIS to EMISstd and change the long name of the to

describe the new field.

call addfld ('EMIS','1',pver,'A','cloud emissivity',phys_decomp)

call addfld ('EMISstd','1', pver,'A','cloud emissivity without

ice',phys_decomp)

II.D: Build and Run (Summary)

1) Build the model, check for errors

2) Modify namelist to write out new fields

3) Submit job to queue

II.D.1: Build

• Change to the $CASEROOT directroy

% cd /home/bluesky/$USER/ccsm3/scripts/b30.ACMatm1

• Build again

% b30.ACMatm1.bluesky.build

– It builds much faster this time because it only rebuilds the

files we have changed

– We could submit the run script now; as long as

SETBLD is defined as AUTO in the env_run file, it should

rebuild before running since there is modified code.

– But building modified code often reveals errors, so we don't

want to wait in the queue to find that out

II.D.1: Build output- look for errors

• If there is an error in the code

– The build script will quit with an error messageERROR: cam.buildexe.csh failed, see atm.buildexe.060602-083803

ERROR: cat /ptmp/bundy/b30.ACMatm1/atm/atm.buildexe.060602-083803

– Then we would need to look at the file to determine the

error in the log file from the build/ptmp/bundy/b30.ACMatm1/atm/atm.buildexe.060602-083803

• Otherwise

– the message will indicate successCCSM BUILD HAS FINISHED SUCCESSFULLY

II.D.2: namelist input history file fields: fincl

• Not all fields with outfld calls are automatically written out.

There is a subset of default fields; in the code, these have a

add_default(NAME) call following the addfld(NAME) call.

• To add a field to the first history file (h0), use the namelist

variable fincl1 = 'EMIS','EMISstd'

Add this to the namelist, as you did for nhtfrq & mfilt

(edit Buildnml_Prestage/cam.buildnml_prestage.csh)• The namelist variables are described in Appendix B of the CAM User's Guide

Fincl1

fincl: List of fields to include on the history files.

The added fields must be in Master Field List (created by addfld calls)

II.D.3: Submit to queue

• After building and modifying the namelist, we are ready to run

– Submit run script to the queue

% llsubmit b30.ACMatm1.bluesky.run

llsubmit: Processed command file through Submit Filter: "/usr/local/loadl/submit_filter".

llsubmit: The job "bs1101en.163917" has been submitted.

– See the job in the queue% llq -u $USER

Id Owner Submitted ST PRI Class Running On

------------------------ ---------- ----------- -- --- ------------ -----------

bs1101en.163917.0 bundy 6/2 08:47 I 50 ded1_rg8

Or for more details% llq -u $USER -l

Take Notes!

• While we're waiting for the model to run, record notes

– In a week, a year or even 10 years, you will want to be able to

find the case name, model configuration, initialization details,

source code modifications and data location.

• A example of notes prepared for this case is available for you to

copy from /home/bluesky/bundy/ccsm3/notes/casenotes_ACM

– Everyone takes notes differently; add and modify this template

III. Plot Results (Summary)

A) Copy data to tempest

B) Latitude by longitude plots of temperature

1)New case

2)Control case

3) the difference

C) More plots

1)Zonal average

2)Compare EMIS and EMISstd

III.A. Copy data to tempest

● Either open a new shell and log in through roy to tempest% ssh -Y roy.ucar.edu

user@roy.ucar.edu's password:

CryptoCard Challenge

UCAR SSH Proxy (? for help)> tempest

● Or ssh from bluesky% ssh -Y tempest

• Make a directory for the history files% mkdir -p /ptmp/$USER/b30.ACMatm1/atm

% cd /ptmp/$USER/b30.ACMatm1/atm

• Copy all atm history files from the mass store% msrcp mss:/USER/csm/b30.ACMatm1/atm/hist/\*.nc . &

● While that is running, set up scripts…next page

Your user name in all CAPS

III.B.1: Lat x Lon plot- edit script

● Copy script to a directory for today% mkdir -p /home/tempest/$USER/ACM_2006/nclscripts

% cd /home/tempest/$USER/ACM_2006/nclscripts

% mkdir b30.ACMatm1

% cd b30.ACMatm1

% cp /home/tempest/bundy/ACM_2006/nclscripts/atm_latlon.ncl .

● Edit today's script with case name and field

% xemacs atm_latlon.ncl

case = "b30.ACMatm1"

field = "T"

level_index = 25

● Save the plotting script with the field name

save as: atm_latlon_T.ncl

III.B.1: Lat x Lon plot- NCL & ghostview

• NCL% ncl atm_latlon_T.ncl

(0) opening /ptmp/$USER/b30.ACMatm1/atm/b30.ACMatm1.cam2.h0.0001-01-06-00000.nc

(0) reading field T

(0) Plot written to /ptmp/$USER/b30.ACMatm1/atm/ll_T_time5_lev992.ps

• View plot% ghostview /ptmp/$USER/b30.ACMatm1/atm/ll_T_time5_lev992.ps

• Need compare to

a control run to see

what changed

III.B.2: Control case- copy data and plot

● Make a directory for the control case b30.ATMcon and copy

or link existing files into your directory% mkdir -p /ptmp/$USER/b30.ACMcon/atm

% ln -s /ptmp/bundy/b30.ACMcon/atm/b30.ACMcon.cam2.h0.0001-01-06-00000.nc

/ptmp/$USER/b30.ACMcon/atm

● Save ncl script as atm_latlon_cntl_T.ncl

and change case name to b30.ACMcon

● NCL% ncl atm_latlon_cntl_T.ncl

● View plot% ghostview /ptmp/$USER/b30.ACMcon/atm/ll_T_time5_lev992.ps

III.B.3: Plot difference= test - cntl

• To plot the difference, you could edit the NCL script to read in both files and subtract the fields.• One easy way is to use the NCO operator ncdiff% cd /ptmp/$USER/b30.ACMatm1/atm% ncdiff -v T,TS b30.ACMatm1.cam2.h0.0001-01-06-00000.nc /ptmp/$USER/b30.ACMcon/atm/b30.ACMcon.cam2.h0.0001-01-06-00000.nc diff.b30.ACMatm1-b30.ACMcon.cam2.h0.0001-01-06-00000.nc

• Copy my (primitive) difference script % cd /home/tempest/$USER/ACM_2006/nclscripts/b30.ACMatm1% cp /home/tempest/bundy/ACM_2006/nclscripts/atm_latlon_diff.ncl .

case = b30.ACMatm1cntl = b30.ACMconfield = “T”

• Save as: atm_latlon_diff_T.ncl

• NCL % ncl atm_latlon_diff_T.ncl

• View plot% ghostview /ptmp/$USER/b30.ACMatm1/atm/diff_ll_T_time5_lev992.ps

III.C: More plots to do

● Surface temperature (TS)Why is this different from T at level = 25?

● Zonal average plotting script/home/tempest/bundy/ACM_2006/nclscripts/atm_zonal.ncl

Vertical coordinate- which way is up?Modify script to do a difference plot

● Zonal average of difference between EMIS, EMISstd

Resources:NCL Homepage http://www.ncl.ucar.edu/get_started.shtml

● Vertical coordinates in CAMhttp://www.ccsm.ucar.edu/models/atm-cam/docs/description/see Figure 3.1, section 3.1.4

IV: Challenge Exercises

● Modify the namelist to write out a second history file (h1) with instantaneous, hourly temperature data

● Plot a time series of the area-weighted globally-averaged hourly data

● Trace the source code subroutine calls to confirm that the emissivity we modified applies to longwave radiation

● Change the temperature dependence to actual ice clouds● Only change the emissivity for ice (or cold) clouds above

500mb● Make a 3-panel plot showing the new case, the control (with

the same contour intervals) and the difference