Questions about case.setup

[billsacks]

In addressing #1668 , I found I have two questions about case.setup for which I cannot find an answer:

(1) What files need to be changed before running case.setup? I know this includes env_mach_pes.xml, and at one point this included batch settings, but: are there still batch settings that need to be changed before running case.setup?; are there others?

(2) When do you need to run ./case.setup --reset as opposed to just rerunning ./case.setup?

@jedwards4b @jgfouca can you please either answer these questions here or update the help for case.setup in mvertens/documentation_updates, and/or the cime web documentation, to answer these questions?

[jedwards4b]

env_mach_pes.xml and env_mach_specific.xml. Batch settings are now updated in the case.submit stage.

./case.setup is the first time it's run ./case.setup --reset thereafter. It used to be a requirement to run
case.setup --clean followed by case.setup - I replaced those two commands with case.setup --reset
but looking at the code in case_setup.py now I don't think that there is any difference between running case.setup and case.setup --reset

[jedwards4b]

Also if you change config_compilers.xml and want a new Macros file generated you can manually remove the current Macros file and run case.setup to generate it again.

[billsacks]

Thanks, @jedwards4b . From looking at the code a bit and playing around with this, it looks like:

1. case.setup --reset sets BUILD_COMPLETE to FALSE; simply running case.setup does not

2. case.setup --reset regenerates the .case.run file (and maybe does some other stuff: I think the whole block of code below is only executed on the first run or a reset), whereas simply running case.setup does not

cime/scripts/lib/CIME/case/case_setup.py

Lines 138 to 175 in fcebaad

	else:
	case.check_pelayouts_require_rebuild(models)
	unlock_file("env_build.xml")
	unlock_file("env_batch.xml")
	case.flush()
	case.check_lockedfiles()
	case.initialize_derived_attributes()
	cost_per_node = case.get_value("COSTPES_PER_NODE")
	case.set_value("COST_PES", case.num_nodes * cost_per_node)
	threaded = case.get_build_threaded()
	case.set_value("SMP_PRESENT", threaded)
	if threaded and case.total_tasks * case.thread_count > cost_per_node:
	smt_factor = max(1.0,int(case.get_value("MAX_TASKS_PER_NODE") / cost_per_node))
	case.set_value("TOTALPES", int(case.total_tasks * max(1.0,float(case.thread_count) / smt_factor)))
	else:
	case.set_value("TOTALPES", case.total_tasks*case.thread_count)
	# May need to select new batch settings if pelayout changed (e.g. problem is now too big for prev-selected queue)
	env_batch = case.get_env("batch")
	env_batch.set_job_defaults([(case.get_primary_job(), {})], case)
	# create batch files
	env_batch.make_all_batch_files(case)
	if get_model() == "e3sm" and not case.get_value("TEST"):
	input_batch_script = os.path.join(case.get_value("MACHDIR"), "template.case.run.sh")
	env_batch.make_batch_script(input_batch_script, "case.run", case, outfile=get_batch_script_for_job("case.run.sh"))
	# Make a copy of env_mach_pes.xml in order to be able
	# to check that it does not change once case.setup is invoked
	case.flush()
	logger.debug("at copy TOTALPES = {}".format(case.get_value("TOTALPES")))
	lock_file("env_mach_pes.xml")
	lock_file("env_batch.xml")

So based on this, I'll probably put in the documentation that, if you want to rerun ./case.setup, you should use ./case.setup --reset. Does that sound good?

[jedwards4b]

sure