[mesa-users] mesa 4411 -- R&R release

[Bill P. <pa...@ki...>]

Hi,

This release has lots of R&R -- Reorganizing and Renaming.

In addition to that, there are lots of new features and one important bug fix.

Details follow.

Cheers,
Bill




The motivation for this upheaval came from the MESA Summer School
where it was pointed out that while most of the naming and
organization in mesa is rational, there are a few glaring exceptions
that make it more difficult for new users to get started.
Of course experienced users, like yourself, have become accustomed
to the current scheme with warts and all, and for you it will be a pain to have
things change.  Sorry about that, but I hope it will be a fairly minor
inconvenience and a major improvement for future users.


REORGANIZING

As you know, mesa is organized as a set of "modules" such as num, eos, star, etc.
Each module creates a library that has an interface defined in its "public"
directory and an implementation defined in its "private" directory.
In the case of star, the library provides routines to do basic operations 
of stellar evolution such as read or initialize a model, evolve a model for 
a single step, write a model profile, etc.   But we need more than that
in order to run a full stellar evolution job.  In the past, all of the extra
things were dumped into star/public along with the library routines.
Now we have added separate directories for the extra files so that
the files in star/public are limited to the actual star library interface.

Here's the new directory structure for mesa/star:

star/public		interface to the star library
	star_lib.f			library procedures for star
	star_def.f			definitions of data for star
	star_def.inc			the extension "dek" has been changed to "inc" for "include"
	star_data.inc		
	star_controls.inc	

	
star/other		user definable routines for modifying and extending the star library
	other_am_mixing.f		transport of angular momemtum
	other_atm.f			surface atmosphere boundary conditions
	other_cgrav.f			variable "constant" G
	other_diffusion.f		gravitational settling and chem diffusion
	other_energy_implicit.f		extra energy source with timescale <= step size
	other_energy.f 			extra energy source with timescale >> step size
	other_eos.f			alternative equation of state routine
	other_kap.f			alternative opacities routine
	other_mesh_functions.f		experiments with new criteria for mesh refinement
	other_mixing.f			alternative routine for setting mixing diffusion coeffs
	other_mlt.f			alternative implementation of mixing length theory
	other_torque.f			extra torque source
	other_wind.f			alternative recipes for wind mass loss
	other_pgstar_plots.f		user defined plots for screen or file using pgstar
	sample_pgstar_plot.f		sample using the other_pgstar_plots function
	inlist_pgstar_other		inlist for sample_pgstar_plot
	

star/job		routines for controlling stellar evolution jobs
	run_star.f			top level routine called by users to run star jobs
	run_star_support.f		job control routines for single star evolution
	standard_run_star_extras.inc	templates for user defined routines called by run star


star/defaults		parameters for star public and star job
	controls.defaults		defaults for &controls namelist
	star_job.defaults 		defaults for &star_job namelist
	pgstar.defaults			defaults for &pgstar namelist
	history_columns.list  		previously located in mesa/data/star_data
	profile_columns.list  		previously located in mesa/data/star_data


star/work		a sample work directory for using mesa/star 
	inlist
	inlist_project
	LOGS
	make
	photos
	src
	...


star/binary_systems	routines for controlling jobs such as Roche Lobe overflow
	[NOTE: expect changes here in the not-too-distant future.]
	rlo_routines.inc
	rlo_binary_routines.inc
	rlo_data.inc
	tide_routines.inc
	

star/astero_adipls	routines for jobs doing asteroseismology using star and adipls
	[NOTE: this used to live in mesa/astero]
	makefile
	astero_search_controls.defaults
	astero_pgstar_controls.defaults
	run_star_extras_adipls.f
	extras_support.f
	star_adipls_support.f
	star_adipls_support_procs.f
	pgstar_echelle_plot.f
	pgstar_echelle_plot_stub.f


star/astero_adipls/work/	a sample work directory for using astero_adipls
	inlist_astero_search_controls
	adipls.c.pruned.in
	redistrb.c.pruned.in
	make
	src
	...




RENAMING


in the LOGS directory, the nth profile is now called profile<n>.data rather than the old name log<n>.data,
and the history file is now called history.data instead of the old name star.log

there is now a default to write the current set of &controls at the same time as the profile.
the file containing the controls for the nth profile is in LOGS/controls<n>.data
note that there is already an option to save the &star_job controls to a file: save_star_job_namelist  

the options for the history.data file are now called "history_columns.list" instead of "log_columns.list"
the optiions for profiles is still called "profile_columns.list"

there are a bunch of changes related to calling the history "history" rather than calling it "log",
and a bunch more for using "profile<n>.data" instead of "star<n>.log"

in run_star_extras, 
	new					old
how_many_extra_history_columns		how_many_extra_log_columns
data_for_extra_history_columns		data_for_extra_log_columns

in &star_job,
	new					old
history_columns_file			log_columns_file

in &controls,
	new					old
do_history_file				do_log_files
history_interval			log_cnt
trace_history_value_name		trace_log_value_name
num_trace_history_values		num_trace_log_values
maxlen_history_column_name		maxlen_log_column_name
star_history_name			star_log_name
star_history_header_name		star_log_header_name
star_history_..._format			star_log_..._format

profile_data_prefix			log_data_prefix
profile_data_suffix			log_data_suffix
profile_data_header_suffix		log_data_header_suffix
write_profiles_flag			do_profiles

write_controls_info_with_profile
controls_data_prefix
controls_data_suffix


MESA_DIR environment variable
	
In &star_job, the control "mesa_data_dir" has been replaced by "mesa_dir".
If the value given for mesa_dir in your inlist is the string of length 0,
then the code uses the value of the MESA_DIR environment variable.
This lets you set mesa_dir = '' in all of your work directories and change
to a new installation of mesa just be changing an environment variable.


In summary, here's an incomplete list of things you'll probably need to do

1) change mesa_data_dir to mesa_dir in inlist &star_job
2) replace "log_column" by "history_column" in run_star_extras
3) replace "log_column" by "history_column" in inlist &star_job
4) replace "log_cnt" by "history_interval" in inlist &controls
5) rename log_columns.list to history_columns.list
6) change "equitorial" to "equatorial" in profile_columns.list



A bug fix you might really care about

I just found and fixed a bug that has been blocking the effect of the special rate factors.
Turns out that the special factor was correctly set to the requested value -- 
but unfortunately that was happening before another routine came along 
and "initialized" the array of factors to all 1's.   So if you were you setting
a rate factor, it wasn't having an effect.   


Other changes

there is now a "max_wind" in the controls along with "min_wind"

the net 1 zone burn tool includes an option to show_Qs for the the reactions

run.f now passes the name 'inlist' to do_run_star so you can change the "root" inlist name if desired.

change in work_standard_makefile for new location of run_star -- now in star/job, was in star/test/src.

added l=3 option to astero.

astero chi^2 as weighted sum of chi^2 for spectro and seismic

add echelle plot to astero (using the other_pgstar_plots function in star)

add pgstar plot for logg vs. logTeff

change astero to save controls to file at start of run

change astero to save best model information to file at end of run

add option for astero to take series of parameter settings from file (for follow to scan grid)

revise diffusion timestep selection to make it more robust (but this still needs more work)
	
decrease default value for mesh_delta_coeff from 1.0 to 0.7 to give better spatial resolution

fix spelling of "equatorial" (it was misspelled as "equitorial")

have removed seulex from num because of problems with 1 zone burn; recommend using rodas4 instead

rename star test_suite case from "astero" to "example_astero"



History window for PGSTAR

this is similar to Cntr_Hist and Surf_Hist, but you get to select the things to plot.
the Hist plot has 4 panels, each with different left and right y axes.
the yaxis choices are given as names that are valid as entries in history_columns.list.
see "Hist window" in star/defaults/pgstar.defaults

Here's an example -- just edit your inlist to change the values to be plotted.