Barely Functional Theories

Musings on science and game design by James Furness.



Energy Level Plotter



A small python script for creating to-scale reaction profile diagrams in PDF form, shared under the MIT license.
You can view the source in your browser here.

Download EnergyLeveller.py


The energy level for a radical isomerisation important in the atmosphere.

The energy level for a radical isomerisation important in atmospheric chemistry.


About

This tool was born when we got sick of seeing yet another MS Paint constructed monstrosity from the students in physical chemistry labs. We don’t blame them, they were making the best of the tools they knew, but we wanted to encourage publication quality in the students reports, and helping them out with a tool to make better diagrams seemed only fair. The script has since found used in a few of my own projects that needed accurate energy profile diagrams, even ending up in published work. As I wrote the script with inexperienced users in mind it tries to be as tolerant to input errors as possible, troopering on where possible, and advising where not.

The script is written in python 2.7 and requires the cairo, pango and pangocairo modules.As well as the os, sys and math standard modules.. It doesn’t require a graphical front end so will happily operate on a headless machine over SSH. Unfortunately the cairo and pango libraries do not come as standard in common python environments, and installing them may be something as a hurdle for less experienced users. If there is interest I may re-write the tool using matplotlib. In the mean time I suggest contacting your local system administrator and asking (nicely) for help setting up your environment, or following instructions found on the web yourself.OSX users can use Macports to install these.


General Operation

The diagram is defined by an input file passed to the script as the first argument. The script is invoked as:

python EnergyLeveler.py inputfile.inp

Running the script without an input file will print an example input file to the terminal.


Input File Structure

The simplest way to understand the input to modify the example given below, though a full description is given here for completeness.

The input file is structured as a block of general parameters for the overall plot appearance followed by a series of states defined in curly brace separated blocks. A state is identified in the script by a unique name allowing the definition of lines showing reaction pathways between named states. Lines beginning with a hash symbol # are ignored by the script and can be used to add comments to input files.Inline comments are not yet supported.


General Input

The following common options control the overall output and are entered as key = value.

output-file File name to save the output to.
width Width (in pixels) of the output image.
height Height (in pixels) of the output image.
font-size Font size of all text.
energy-units Unit label for the vertical scale.

A number of pre-defined colours are available by name as red, blue, green, purple, orange, yellow, brown, pink, black, gray.

New colours can be defined with a name and RGB values given as the range [0-1]. For example:

new colour = DarkBlue,0.27,0.51,0.71


State Input

Points in the diagram are defined as individual states with various properties defined in the input using curly brace blocks with the following fields entered again as key = value.

name The name used by the program to refer to the state when drawing links. The name is not displayed in the final image.
label The name displayed for the state above the energy level line. Accepts pango markup formatting.
text-colour The colour used for the state’s label and numerical energy value. Colours defined in general input can be requested by name.
state-colour The colour used for drawing the state’s energy line. Colours defined in general input can be requested by name here.
energy The energy of the state, defining its vertical position, printed below the state line.
column The horizontal position of the state, defined as an integer column number starting from 1.
label-offset A shift in pixels to the state label text, defined as x,y. Useful for fixing overlapping state labels.
energy-text-offset A shift in pixels to the printed energy text, defined as x,y.
links-to Links this state to others in the diagram, discussed in detail below.

States can be linked together to show reaction pathways using the state option links-to with a comma delimited list of named states to connect to. A dashed line is drawn from the right edge of the current state to the left edge of the listed state. A colour for this line can be specified using :colour after the destination state name. User defined colours can be used. For example:

links-to = state2:red,state3:blue

The label drawn above the states uses the pango text attribute markup language to allow super and sub scripts in the labels.


Example Input

An example input is given here, same is printed if the script is run without an input file.

output-file     = example.pdf
width           = 700
height          = 450
font-size       = 10
energy-units    = dE  kJ/mol

#   This is a comment. Lines that begin with a # are ignored.
#   Available colours are 'red', 'blue, 'green' 'purple' 'orange' 'yellow' 'brown' 'pink' 'black' and 'gray'.
#   New colours are declared with rgb 0.0-1.0 in the style:
#   NEW COLOUR = NAME,RED,GREEN,BLUE  

new colour = DarkBlue,0.27,0.51,0.71

#   Now begins the states input

#------  Path 1 ----------------

#   Add the first path, all paths are relative to the reactant energies so
#   start at zero

{
    name        = reactants
    text-colour = black
    label       = CH<sub>3</sub>O<sup><b>.</b></sup> + X
    energy      = 0.0
    state-colour= black
    links-to    = pre-react1:red, transition2:blue, pre-react3:green
    column      = 1
}

{
    name        = pre-react1
    text-colour = red
    label       = CH<sub>3</sub>O<sup><b>.</b></sup> - X
    energy      = -10.5
    state-colour= red
    links-to    = transition1:red
    column      = 2
}

{
    name        = transition1
    text-colour = red
    label       = [CH<sub>3</sub>O<sup><b>.</b></sup> - X]
    energy      = +20.1
    state-colour= red
    links-to    = post-react1:red
    column      = 3
}

{
    name        = post-react1
    text-colour = red
    label       = <sup><b>.</b></sup>CH<sub>2</sub>OH - X
    energy      = -8.2
    label-offset= 0,25
    energy-text-offset = 0,17
    state-colour= red
    links-to    = products:red
    column      = 4
}

{
    name        = products
    text-colour = black
    label       = <sup><b>.</b></sup>CH<sub>2</sub>OH + X
    energy      = -2.0
    state-colour= black
    column      = 5
}
#------  Path 2 ----------------
{
    name        = transition2
    text-colour = blue
    label       = [CH<sub>3</sub>O<sup><b>.</b></sup>]
    energy      = +30.1
    state-colour= blue
    links-to    = products:blue
    column      = 3
}

#------  Path 3 ----------------
{
    name        = pre-react3
    text-colour = green
    label       =    CH<sub>3</sub>O<sup><b>.</b></sup> - X
    energy      = -8.3
    label-offset= 0,-15
    energy-text-offset = 0,-20
    state-colour= green
    links-to    = transition3:green
    column      = 2
}

{
    name        = transition3
    text-colour = green
    label       = [CH<sub>3</sub>O<sup><b>.</b></sup> - X]
    energy      = +25.4
    state-colour= green
    links-to    = post-react3:green
    column      = 3
}

{
    name        = post-react3
    text-colour = green
    label       = <sup><b>.</b></sup>CH<sub>2</sub>OH - X
    energy      = -6.1
    label-offset= 0,-15
    energy-text-offset = 0,-20
    state-colour= green
    links-to    = products:green
    column      = 4
}

Running this input produces the diagram shown at the top of the page.


License

This code is shared under the MIT license Copyright 2017 James Furness.
You are free to use, modify and distribute the code, though recognition of my effort is appreciated!

If you require a feature that is missing from the script please feel free to get in contact with me and I’ll look at implementing it, though no guarantee is made. Alternatively you can dig in and add it yourself. If you do I’d love to hear about it and update the copy here with your new functionality (credited of course).