This is an Emacs major mode and some related minor-modes intended for use when editing the work directory files (inlists and run_star_extras.f) used by the MESA stellar evolution code. It is descendant of (and replacement for) mesa-minor-mode.
Its key features are:
- For inlists
- syntax highlighting
- quick access to documentation with xref/etags
- constrained editing
- automatic formatting
- For run_star_extras
- easy “activation”
- automatic bookkeeping
For me at least, it significantly speeds up a number of common operations.
To use this software, you must have Emacs 25.1 or newer. (In Emacs 25, xref replaced etags’s front-end and UI and I switched things over to xref.) If you are using emacs 24.X, there is an emacs24 branch that should still be compatible.
If you are using MESA on a remote system where only older emacs versions are available, you may want to consider running a newer version locally and editing your inlists using TRAMP.
The best way to get mesa-mode is to clone this repository
git clone https://github.com/jschwab/mesa-major-mode.git
If you don’t want to use git, you can also download a zipfile using the “Clone or download” button above.
Make sure that the .el files are in your load-path and then require
them in your Emacs init file. Replace /path/to/mesa-major-mode with
the path to the the folder where you placed the mesa-mode.el file.
(add-to-list 'load-path "/path/to/mesa-major-mode/") (require 'mesa-mode) (require 'run-star-extras)
You can have Emacs edit every file whose name starts with inlist using this major mode by adding
(add-to-list 'auto-mode-alist '("/inlist[^/]*$" . mesa-mode))
to your Emacs init file.
I recommend also opening MESA defaults files with mesa-mode in order to get the syntax highlighting. I also recommend using the read-only view-mode which will prevent you from confusing them with your inlists and editing them accidentally.
(add-to-list 'auto-mode-alist '("\\.defaults$" . (lambda () (mesa-mode) (view-mode))))
For run_star_extras.f and run_binary_extras.f I recommend
f90-mode and the run_star_extras minor mode.
(add-to-list 'auto-mode-alist '("/run_star_extras.f$" . (lambda () (f90-mode) (run-star-extras-minor-mode))))
(add-to-list 'auto-mode-alist '("/run_binary_extras.f$" . (lambda () (f90-mode) (run-star-extras-minor-mode))))
There is an included minimal_init.el file that contains these
commands.
There are now three ways that you can tell mesa-mode about where MESA lives. These are listed in order of reverse precedence.
(The code that figures out and controls what version of MESA you’re using has been abstracted into mesa-version.el.)
If you don’t do anything, mesa-version will try to get the value of MESA_DIR using getenv. Unless you’ve modified the value within emacs (via setenv), this is probably the value of MESA_DIR in the environment where you started emacs.
If you only have one version of MESA installed and MESA_DIR is set
when you start emacs, this is a good option. The mode line will show
[MESA_DIR] if this is how the version was set.
If you set the variable mesa-version-mesa-dir, mesa-mode will use
that path as the MESA_DIR.
(setq mesa-version-mesa-dir "/home/jschwab/Software/mesa-r8118")
If you only use one version of MESA, this is also a good option. The
mode line will show [mesa-dir] if this is how the version was set.
If you have multiple MESA versions installed, you may want to take a look at mesa-init. Whether or not use that software, you should use a mesa-init style version list to tell mesa-mode about all your MESA versions.
Create a file named .mesa_init in your home directory. List the
paths to your various MESA versions using ini format, as below.
[r7624]
MESA_DIR = /path/to/mesa-r7624
[r8118]
MESA_DIR = /path/to/mesa-r8118
You can have one or more of these entries.
You also want to specify the default version of MESA you want to emacs to use. Add
;; set default MESA version (setq mesa-version-default "r7624")
where “r7624” is the identifier (that you specified earlier in
~.mesa_init) of whatever version of MESA you want to be the default.
The mode line will show “[id]”, identifier (that you specified earlier in
~.mesa_init) of whatever version of MESA you want to be the default.
If you’re using this option, you can use C-c C-v to change the MESA
mode associated with the buffer you’re visiting. The MESA version is
buffer-local, so different buffers can use different MESA versions.
This is one of the primary motivations for the major-mode. The inlist will be syntax highlighted. By default, the following faces are used.
| Thing | Face |
|---|---|
| comment | font-lock-comment-face |
| namelist name | font-lock-function-name-face |
| option (key) | font-lock-variable-name-face |
| option (value, boolean) | font-lock-builtin-face |
| option (value, string) | font-lock-string-face |
| option (value, number) | font-lock-constant-face |
You can change the colors assigned to each of the faces using emacs’ built-in customize facilities.
- Put your cursor on the text you don’t like
- Do
M-x describe-text-properties - Click on
font-lock-constant-face(or similar) - Click on
customize-face - Click on
[Choose] - Pick a new color
- Click on
[Apply and Save]
This is the other primary motivation for the major-mode.
The command C-c C-d will open another window and show you to a
variable’s definition in the appropriate .defaults file. This lets
you see the default value and the surrounding documentation. You can
delete or resize this window using standard emacs window commands.
For example, you can delete it using the command C-x 1. You can
also use the command C-x o to switch to this other window and then
look around in the defaults file.
Emacs has a huge number of searching and completion functions that can
make use of tags. For example, the command M-. will jump you to a
variable’s definition in the appropriate .defaults file. M-, will
jump you back to your place in the inlist. Your completion command
M-/ will also be able to take advantage of tags. To learn more
about what tags are and what they can do, read the Emacs docs.
The default tag file will include everything in the star_job,
controls, pgstar, binary_job, and binary_controls namelists. If a
TAGS file doesn’t exist when mesa-mode starts or the version changes,
it will try and create one. To regenerate the TAGS file (for example,
after you upgrade MESA), use M-x mesa-regen-tags.
The mode provides a number of commands that allow you to edit options in a particular way. Using these commands is often quicker and prevents typos.
Here’s a summary table. More detail is below.
| Key | Effect |
|---|---|
C-c C-c | Toggle comment status |
C-c C-e | Edit option value |
C-c C-f | Toggle strict formatting |
C-c C-i | Edit option index |
C-c C-p | Insert PGSTAR plot template |
C-c C-r | Reset option to default value |
C-c C-t | Toggle boolean value |
C-c C-c will toggle the comment status of lines, regions, etc.
C-c C-e will replace the value of the option on the current line
with the text entered in the minibuffer. With a prefix argument
C-u, the minibuffer will initially contain the current value.
C-c C-f will toggle strict formatting mode (see below) on/off.
C-c C-i will replace the value of an array index with the text
entered in the minibuffer. If no region is active, this replacement
will occur on the current line. If a region is active, this
replacement will occur for all options in the region that have an
index.
When point is in the pgstar namelist, C-c C-p prompts the user from
a list of PGSTAR plots. When one is selected, that sub-section of the
pgstar.defaults file is inserted at point. This makes it easy to
quickly start including a new plot.
C-c C-r will reset an option to its default value (i.e. the one
specified in the MESA .defaults file).
C-c C-t will switch the option value between .true. and .false..
When strict formatting is active, mesa-mode gives you very little control over your inlist formatting. This strictness was inspired by Mike McCourt’s athinput-mode.
When you save the inlist, extraneous whitespace will be stripped and inlist commands will be indented.
The only part of this that can be customized (unless you’re willing to edit the mode directly) is the string used for the indent. For example, if you prefer 4 space indents, you could set
(setq mesa-indent-string " ")
If there are additional formatting aspects that are important, please write to me or send a pull request.
By default, strict formatting mode is off, but you can activate it on
a per-buffer basis with C-c C-f. If you would like it to be on by
default, you can set
(setq mesa-mode-enforce-formatting-default t)
In a brand-new run_star_extras.f, there’s a line
include 'standard_run_star_extras.inc'that pulls in all the default functions.
The first step in starting a new run_star_extras is to replace this
include statement with the code itself. To do so, just press C-c
C-r.
When I add an extra history or profile column, I always forget to
update the number. There’s an a hook that will update the value of
how_many_extra_history_columns or how_many_extra_history_columns
each time to save. Never forget to do this again.
This feature is off by default. To turn it on, add
(setq rse-update-extra-column-counts t)
to your configuration.
When you save your run_star_extras.f, you can have it automatically recompiled.
This feature is off by default. To turn it on, add
(setq rse-recompile-on-save t)
to your configuration.
I use this with the latest Emacs release on Linux, so that’s where it is least likely to be broken. I’m also not much of an elisp hacker, so you probably shouldn’t take anything done here as representative of the “right way”. Issues/Pull requests are welcome!