CIME.case package

Submodules

CIME.case.case module

Wrapper around all env XML for a case.

All interaction with and between the module files in XML/ takes place through the Case module.

class CIME.case.case.Case(case_root=None, read_only=True)

Bases: object

https://github.com/ESMCI/cime/wiki/Developers-Introduction The Case class is the heart of the CIME Case Control system. All interactions with a Case take part through this class. All of the variables used to create and manipulate a case are defined in xml files and for every xml file there is a python class to interact with that file.

XML files which are part of the CIME distribution and are meant to be readonly with respect to a case are typically named config_something.xml and the corresponding python Class is Something and can be found in file CIME.XML.something.py. I’ll refer to these as the CIME config classes.

XML files which are part of a case and thus are read/write to a case are typically named env_whatever.xml and the cooresponding python modules are CIME.XML.env_whatever.py and classes are EnvWhatever. I’ll refer to these as the Case env classes.

The Case Class includes an array of the Case env classes, in the configure function and it’s supporting functions defined below the case object creates and manipulates the Case env classes by reading and interpreting the CIME config classes.

This class extends across multiple files, class members external to this file are listed in the following imports

apply_user_mods(user_mods_dir=None)

User mods can be specified on the create_newcase command line (usually when called from create test) or they can be in the compset definition, or both.

archive_last_restarts(archive_restdir, rundir, last_date=None, link_to_restart_files=False)

Convenience function for archiving just the last set of restart files to a given directory. This also saves files attached to the restart set, such as rpointer files and necessary history files. However, it does not save other files that are typically archived (e.g., history files, log files).

Files are copied to the directory given by archive_restdir.

If link_to_restart_files is True, then symlinks rather than copies are done for the restart files. (This has no effect on the history files that are associated with these restart files.)

cancel_batch_jobs(jobids)

case_cmpgen_namelists(compare=False, generate=False, compare_name=None, generate_name=None, baseline_root=None, logfile_name='TestStatus.log')

case_run(skip_pnl=False, set_continue_run=False, submit_resubmits=False)

case_setup(clean=False, test_mode=False, reset=False, keep=None)

case_st_archive(last_date_str=None, archive_incomplete_logs=True, copy_only=False, resubmit=True)

Create archive object and perform short term archiving

case_test(testname=None, reset=False, skip_pnl=False)

check_DA_settings()

check_all_input_data(protocol=None, address=None, input_data_root=None, data_list_dir='Buildconf', download=True, chksum=False)

Read through all files of the form *.input_data_list in the data_list_dir directory. These files contain a list of input and boundary files needed by each model component. For each file in the list confirm that it is available in input_data_root and if not (optionally download it from a server at address using protocol. Perform a chksum of the downloaded file.

check_case()

check_if_comp_var(vid)

check_input_data(protocol='svn', address=None, input_data_root=None, data_list_dir='Buildconf', download=False, user=None, passwd=None, chksum=False, ic_filepath=None)

For a given case check for the relevant input data as specified in data_list_dir/*.input_data_list in the directory input_data_root, if not found optionally download it using the servers specified in config_inputdata.xml. If a chksum file is available compute the chksum and compare it to that in the file. Return True if no files missing

check_lockedfile(filebase)

check_lockedfiles(skip=None)

Check that all lockedfiles match what’s in case

If caseroot is not specified, it is set to the current working directory

check_pelayouts_require_rebuild(models)

Create if we require a rebuild, expects cwd is caseroot

check_timestamps(short_name=None)

clean_up_lookups(allow_undefined=False)

configure(compset_name, grid_name, machine_name=None, project=None, pecount=None, compiler=None, mpilib=None, pesfile=None, gridfile=None, multi_driver=False, ninst=1, test=False, walltime=None, queue=None, output_root=None, run_unsupported=False, answer=None, input_dir=None, driver=None, workflowid='default', non_local=False, extra_machines_dir=None)

copy(newcasename, newcaseroot, newcimeroot=None, newsrcroot=None)

create(casename, srcroot, compset_name, grid_name, user_mods_dir=None, machine_name=None, project=None, pecount=None, compiler=None, mpilib=None, pesfile=None, gridfile=None, multi_driver=False, ninst=1, test=False, walltime=None, queue=None, output_root=None, run_unsupported=False, answer=None, input_dir=None, driver=None, workflowid='default', non_local=False, extra_machines_dir=None)

create_caseroot(clone=False)

create_clone(newcaseroot, keepexe=False, mach_dir=None, project=None, cime_output_root=None, exeroot=None, rundir=None, user_mods_dir=None)

Create a case clone

If exeroot or rundir are provided (not None), sets these directories to the given paths; if not provided, uses default values for these directories. It is an error to provide exeroot if keepexe is True.

create_dirs()

Make necessary directories for case

create_namelists(component=None)

Create component namelists

flush(flushall=False)

get_batch_jobs()

get_build_threaded()

Returns True if current settings require a threaded build/run.

get_case_root()

Returns the root directory for this case.

get_compset_components()

get_compset_var_settings(files)

get_env(short_name, allow_missing=False)

get_first_job()

get_job_info()

Get information on batch jobs associated with this case

get_latest_cpl_log(coupler_log_path=None, cplname='cpl')

find and return the latest cpl log file in the coupler_log_path directory

get_mpirun_cmd(job=None, allow_unresolved_envvars=True, overrides=None)

get_primary_component()

get_primary_job()

get_record_fields(variable, field)

get_record_fields gets individual requested field from an entry_id file this routine is used only by xmlquery

get_resolved_value(item, recurse=0, allow_unresolved_envvars=False)

get_type_info(item)

get_value(item, attribute=None, resolved=True, subgroup=None)

get_values(item, attribute=None, resolved=True, subgroup=None)

initialize_derived_attributes()

These are derived variables which can be used in the config_* files for variable substitution using the {{ var }} syntax

is_save_timing_dir_project(project)

Check whether the project is permitted to archive performance data in the location specified for the current machine

load_env(reset=False, job=None, verbose=False)

read_xml()

report_job_status()

restore_from_archive(rest_dir=None, dout_s_root=None, rundir=None, test=False)

Take archived restart files and load them into current case. Use rest_dir if provided otherwise use most recent restore_from_archive is a member of Class Case

set_comp_classes(comp_classes)

set_file(xmlfile)

force the case object to consider only xmlfile

set_initial_test_values()

set_lookup_value(item, value)

set_model_version(model)

set_valid_values(item, valid_values)

Update or create a valid_values entry for item and populate it

set_value(item, value, subgroup=None, ignore_type=False, allow_undefined=False, return_file=False)

If a file has been defined, and the variable is in the file, then that value will be set in the file object and the resovled value is returned unless return_file is True, in which case (resolved_value, filename) is returned where filename is the name of the modified file.

stage_refcase(input_data_root=None, data_list_dir=None)

Get a REFCASE for a hybrid or branch run This is the only case in which we are downloading an entire directory instead of a single file at a time.

submit(job=None, no_batch=False, prereq=None, allow_fail=False, resubmit=False, resubmit_immediate=False, skip_pnl=False, mail_user=None, mail_type=None, batch_args=None, workflow=True)

submit_jobs(no_batch=False, job=None, skip_pnl=None, prereq=None, allow_fail=False, resubmit_immediate=False, mail_user=None, mail_type=None, batch_args=None, dry_run=False, workflow=True)

test_env_archive(testdir='env_archive_test')

test_st_archive(testdir='st_archive_test')

update_env(new_object, env_file, blow_away=False)

Replace a case env object file

valid_compset(compset_name, compset_alias, files)

Add stub models missing in <compset_name>, return full compset name. <files> is used to collect set of all supported components.

CIME.case.case_clone module

create_clone is a member of the Case class from file case.py

CIME.case.case_clone.create_clone(self, newcaseroot, keepexe=False, mach_dir=None, project=None, cime_output_root=None, exeroot=None, rundir=None, user_mods_dir=None)

Create a case clone

If exeroot or rundir are provided (not None), sets these directories to the given paths; if not provided, uses default values for these directories. It is an error to provide exeroot if keepexe is True.

CIME.case.case_cmpgen_namelists module

Library for case.cmpgen_namelists. case_cmpgen_namelists is a member of Class case from file case.py

CIME.case.case_cmpgen_namelists.case_cmpgen_namelists(self, compare=False, generate=False, compare_name=None, generate_name=None, baseline_root=None, logfile_name='TestStatus.log')

CIME.case.case_run module

case_run is a member of Class Case ‘

CIME.case.case_run.case_run(self, skip_pnl=False, set_continue_run=False, submit_resubmits=False)

CIME.case.case_setup module

Library for case.setup. case_setup is a member of class Case from file case.py

CIME.case.case_setup.case_setup(self, clean=False, test_mode=False, reset=False, keep=None)

CIME.case.case_st_archive module

short term archiving case_st_archive, restore_from_archive, archive_last_restarts are members of class Case from file case.py

CIME.case.case_st_archive.archive_last_restarts(self, archive_restdir, rundir, last_date=None, link_to_restart_files=False)

Convenience function for archiving just the last set of restart files to a given directory. This also saves files attached to the restart set, such as rpointer files and necessary history files. However, it does not save other files that are typically archived (e.g., history files, log files).

Files are copied to the directory given by archive_restdir.

If link_to_restart_files is True, then symlinks rather than copies are done for the restart files. (This has no effect on the history files that are associated with these restart files.)

CIME.case.case_st_archive.case_st_archive(self, last_date_str=None, archive_incomplete_logs=True, copy_only=False, resubmit=True)

Create archive object and perform short term archiving

CIME.case.case_st_archive.get_histfiles_for_restarts(rundir, archive, archive_entry, restfile, testonly=False)

query restart files to determine history files that are needed for restarts

Not doc-testable due to filesystem dependence

CIME.case.case_st_archive.restore_from_archive(self, rest_dir=None, dout_s_root=None, rundir=None, test=False)

Take archived restart files and load them into current case. Use rest_dir if provided otherwise use most recent restore_from_archive is a member of Class Case

CIME.case.case_st_archive.test_env_archive(self, testdir='env_archive_test')

CIME.case.case_st_archive.test_st_archive(self, testdir='st_archive_test')

CIME.case.case_submit module

case.submit - Submit a cesm workflow to the queueing system or run it if there is no queueing system. A cesm workflow may include multiple jobs. submit, check_case and check_da_settings are members of class Case in file case.py

CIME.case.case_submit.check_DA_settings(self)

CIME.case.case_submit.check_case(self)

CIME.case.case_submit.submit(self, job=None, no_batch=False, prereq=None, allow_fail=False, resubmit=False, resubmit_immediate=False, skip_pnl=False, mail_user=None, mail_type=None, batch_args=None, workflow=True)

CIME.case.case_test module

Run a testcase. case_test is a member of class Case from case.py

CIME.case.case_test.case_test(self, testname=None, reset=False, skip_pnl=False)

CIME.case.check_input_data module

API for checking input for testcase

CIME.case.check_input_data.check_all_input_data(self, protocol=None, address=None, input_data_root=None, data_list_dir='Buildconf', download=True, chksum=False)

Read through all files of the form *.input_data_list in the data_list_dir directory. These files contain a list of input and boundary files needed by each model component. For each file in the list confirm that it is available in input_data_root and if not (optionally download it from a server at address using protocol. Perform a chksum of the downloaded file.

CIME.case.check_input_data.check_input_data(case, protocol='svn', address=None, input_data_root=None, data_list_dir='Buildconf', download=False, user=None, passwd=None, chksum=False, ic_filepath=None)

For a given case check for the relevant input data as specified in data_list_dir/*.input_data_list in the directory input_data_root, if not found optionally download it using the servers specified in config_inputdata.xml. If a chksum file is available compute the chksum and compare it to that in the file. Return True if no files missing

CIME.case.check_input_data.md5(fname)

performs an md5 sum one chunk at a time to avoid memory issues with large files.

CIME.case.check_input_data.stage_refcase(self, input_data_root=None, data_list_dir=None)

Get a REFCASE for a hybrid or branch run This is the only case in which we are downloading an entire directory instead of a single file at a time.

CIME.case.check_input_data.verify_chksum(input_data_root, rundir, filename, isdirectory)

For file in filename perform a chksum and compare the result to that stored in the local checksumfile, if isdirectory chksum all files in the directory of form .

CIME.case.check_lockedfiles module

API for checking locked files check_lockedfile, check_lockedfiles, check_pelayouts_require_rebuild are members of Class case.py from file case.py

CIME.case.check_lockedfiles.check_lockedfile(self, filebase)

CIME.case.check_lockedfiles.check_lockedfiles(self, skip=None)

Check that all lockedfiles match what’s in case

If caseroot is not specified, it is set to the current working directory

CIME.case.check_lockedfiles.check_pelayouts_require_rebuild(self, models)

Create if we require a rebuild, expects cwd is caseroot

CIME.case.preview_namelists module

API for preview namelist create_dirs and create_namelists are members of Class case from file case.py

CIME.case.preview_namelists.create_dirs(self)

Make necessary directories for case

CIME.case.preview_namelists.create_namelists(self, component=None)

Create component namelists

Module contents