Major mode for editing MESA inlist files
Emacs Lisp
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
LICENSE
README.org
mesa-mode.el
mesa-version.el
minimal-init.el
run-star-extras.el

README.org

mesa-major-mode

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.

Prerequisites

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.

Installation

Download mesa-mode

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.

Tell emacs to use the mode(s)

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.

Tell mesa-mode which MESA version(s) you want to use

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.)

Get MESA_DIR from your environment

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.

Specify a single MESA_DIR in your emacs config

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.

Use mesa-init style version list (multiple MESA versions)

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.

Features and Usage (Inlists)

Syntax highlighting

This is one of the primary motivations for the major-mode. The inlist will be syntax highlighted. By default, the following faces are used.

ThingFace
commentfont-lock-comment-face
namelist namefont-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]

Quick access to documentation

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.

Constrained editing

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.

KeyEffect
C-c C-cToggle comment status
C-c C-eEdit option value
C-c C-fToggle strict formatting
C-c C-iEdit option index
C-c C-pInsert PGSTAR plot template
C-c C-rReset option to default value
C-c C-tToggle boolean value

Toggle comment status

C-c C-c will toggle the comment status of lines, regions, etc.

Edit option value

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.

Toggle strict formatting

C-c C-f will toggle strict formatting mode (see below) on/off.

Edit option index

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.

Insert PGSTAR plot template

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.

Reset option to default value

C-c C-r will reset an option to its default value (i.e. the one specified in the MESA .defaults file).

Toggle boolean values

C-c C-t will switch the option value between .true. and .false..

Strict formatting

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)

Features and Usage (Fortran)

Easy “activation”

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.

Automatic bookkeeping

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.

Automatic compilation (experimental)

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.

Caveats

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!