TDB Highlighter

| Features | FAQ | Examples for Different Themes | GitHub Repository |

You didn't know you can't do CALPHAD without it.

This VS Code Language Extension, developed by Adam M. Krajewski in Prof. Zi-Kui Liu's group at The Pennsylvania State University, provides syntax highlighting for the Thermodynamic DataBase (TDB) files used in the CALPHAD community to describe thermodynamic properties of materials. You can find them alongside publications in the CALPHAD Journal published by Elsevier, or in the Thermodynamic DataBase DataBase (TDBDB) maintained by Prof. van de Walle group at Brown University.

Most critically, if something is highlighted differently than you expect, you know something may be wrong with it :). E.g., in +1.95033E-07*T**3-.01798O876*T**2+78.5244752*T*LN(T)-722.59722*T+229382.886-93813648*T**(-1); 3290 Y one of the numbers is not a number and will be red. Guess which one...? Likewise, that LAVE_C36 phase you just typed will stand out.

Note: Unsolicited feedback, feature requests, and pull requests are happily accepted!

Features

• Phases, species, elements and other critical elements of the database, are formatted with highly visible fonts and colors, speeding up the process of navigating, reading, and editing the files tremendously.

• References, notes, comments, optionals, and otherwise less critical parts of the database, are formatted with subtle formatting to reduce visual clutter.

• Temperature (T) and its powers/logs/exps in equations are formatted with bright red colors to immediately pinpoint where a given part of the polynomial is located.

• Function names are exposed within the equations to make them stand out from numbers and be easier to read.

• A number of TDB syntax keywords are specifically highlighted in neutral colors matching their functions to make them stand out in case of typos.

Together, they yield the following neat-looking TDB header and function definitions:

and the main body of thermodynamic model parameters:

Oh! And it works in the dark mode, too!

We have tested that it performs very well with a number of themes, including: (VSCode Default) Light Modern, Quiet Light, Solarized Light, Monokai, Monokai Dimmed, Synthwave '84, and (VSCode Default) Dark Modern. You can see some of the example renderings below. If you find that TDB Highlighter does not work well with your theme, please open an issue in this repository and we will try to fix it.

Install

VS Code

Installing TDB Highlighter in VS Code is trivial, as it is released through the official Microsoft Marketplace and the only thing you need to do is to go to "Extensions" tab (left edge, center) by clicking its icon (4 squares, one detached) and press "Install".

GitHub Dev Mode (github.dev)

You may not know, but GitHub repositories can be run in developer mode with the same graphical interface as VS Code. You can give it a try by going to any repository with TDB files (like this one for high-entropy alloys) and simply pressing the period key (a.k.a dot or .) on your keyboard. TDB Highlighter was designed to be fully compatible with that interface and you can install just like in the VS Code instructions above.

The whole process should not take more than one minute and you will be ready to highlight your TDBs. If you want to try it out on your own files, you can just drag and drop them into the "Explorer" tab (left edge, first from the top) and it will be persisted in your browser (locally!) until you reset your browser cache or restart your computer. If you want to persist things, you can use local VS Code or set up your own GitHub repository and Commit&Push your progress under "Source Control" tab.

CotEditor

Installing TDB Highlighter in CotEditor, which happens to be my favorite text editor on Mac, is also very straightforward. Plese follow these dedicated instructions.

JetBrains / IntelliJ / PyCharm

The source code of TDB Highlighter is fully compatible with IntelliJ, PyCharm, and other JetBrains products through their TextMate Bundles default extension, so, like with CotEditor, there is no need to install any plugins.

Simply obtain our source code by either (a) cloning the repository, (b) downloading it as ZIP by going to Code<> > Local > Download ZIP and unpacking, or (c) downloading it as ZIP from one of the releases and unpacking. Make sure to place files in a location you will not delete in the future (like Documents rather than Downloads). Once you are ready, in your JetBrains product, go to Settings.. > Editor > TextMate Bundles and click on the plus button (+) to add a new bundle, then navigate to the TDB Highlighter source code root (you should see package.json but grayed-out), and, finally, click Open. Done! You should now have syntax highlighting of all of your .tdb and .TDB files.

FAQ

No known errors at this time! However, in some cases listed below, the highlighting may not be perfect due to the arbitrary nature of the TDB files and the limitations of the approach.

User-Defined Phases

The phase highlighting is not perfect in a way that it will never cover all the cases since names are arbitrary user choices and can be any string. Thus, without interpreting the TDB file (as opposed to lexing it like we do here), it is impossible to know what is a phase in every context.

Thus, we rely on a list of common phase name patterns that are known to be used in the community. They are currently (as of V1.2.0) covered by this regex (where \\w* can be interpreted as "any characters remaining in word", \\d is any digit, and | is "or" operator):

"\\b(ELECTRON_GAS|VACUUM|GAS|LIQUID|IONIC_L\\w*|FCC\\w*|BCC\\w*|HCP\\w*|DHCP|CBCC\\w*|DELTA|DOUBLE\\w*|DIA\\w*|DIAMOND\\w*|BCT\\w*|RHO\\w*|ORTHORHOMBIC\\w*|TETRAGONAL\\w*|LAVES\\w*|CEMENTITE\\w*|SIGMA\\w*|MU\\w*|LAMBDA\\w*|ETA\\w*|BETA\\w*|GRAPHITE\\w*|THETA\\w*|GAMMA\\w*|C14|C15|C36|ORT|R_PHASE|AMORPHOUS\\w*|\\w*_AMORPHOUS|\\w*_FCC|\\w*_BCC|\\w*_HCP|\\w*_BCT|\\w*_ALPHA|\\w*_PRIME|\\w*_BETA|\\w*_GAMMA|\\w*_DELTA|\\w*_EPSILON|\\w*_ETA|\\w*MU|\\w*_SIGMA|\\w*_TAU|\\w*_D019|\\w*_D83|\\w*_A\\d|\\w*_A\\d\\d|\\w*_B\\d|\\w*_B\\d\\d|\\w*_C\\d|\\w*_C\\d\\d|\\w*_D\\d|\\w*_D\\d\\d|\\w*_E\\d|\\w*_E\\d\\d|\\w*_H\\d|\\w*_H\\d\\d|\\w*_L\\d|\\w*_L\\d\\d|\\w*_S\\d|\\w*_S\\d\\d)\\b"

You will notice all compound-based names (both explicit NACL and anonymous M23C6) are not covered and this is by design, due to both practical and fundamental issues using such ambiguous names can introduce, even though they are very convenient and commonly used. At the same time, you can quickly adjust this by appending it explicitly with Strukturbericht designation, e.g. NACL_B2 or CR23C6_D84, and everything will work as expected.

If you believe something is missing, please open an issue in this repository where you secify the phase name you wish to recognize and we will try to add it.

If you wish to add something yourself, unsolicited pull requests are very welcome. To do so, adjust regexes in the tdb.tmLanguage.json file and open a pull request.

Names of Species

Similar to phases, species names can be arbitrarily set by users, but in this case, the number is so large that it is not feasible to cover even the common ones, as even the same ion can be found written differently across research groups; e.g., Fe3+, Fe+3, 3+Fe, 3Fe, etc.

If you wish to highlight your species, please add them to your local phases list and avoid opening a pull request for this.

Function Names Not Recognized in Equations

Most likely, your function name does not have the # at the end of its name, which is required for it to be recognized as a function. This is intentional, as otherwise, they would conflict custom user-defined species names, which are not provided by default, but can be added by the user and some of them may rely on it.

Line Lenght Limit

Some software, like the very popular Thermo-Calc, has a limit on the length of a line in the TDB file, which is 80 characters following the legacy of Fortran standard. We do not enforce this limit in the syntax highlighting, as not all software has this limit (e.g. pycalphad).

However, if you wish to enforce this limit, you can quickly do so by adding the following to your user settings.json file in VS Code:

"editor.rulers": [80]

Example Renderings

Light Modern (VSCode Default Light)

Quiet Light

Solarized Light

Monokai

Monokai Dimmed

Synthwave '84

Dark Modern (VSCode Default Dark)

Modifying the Theme to Your Liking

In VS Code, language extensions are meant to use a color theme chosen by the user and thus are, by design, prohibited from making modifications to them. Therefore, TDB Highlighter has to work with existing so-called tokens that are provided by the theme. In some cases, like in [the Dark Modern (VSCode Default Dark)] theme, some critical tokens are explicitly defined to be the same, and there is little we can do about it.

Fortunately, as the user, you have complete control over theme customizations! You can, for instance, add the following to your settings.json file to make the phase tokens (markup.heading) bold gold (#D0B344) color in the Default Dark Modern theme:

"editor.tokenColorCustomizations": {
    "[Default Dark Modern]": {"textMateRules": [{"scope": "markup.heading","settings": {"foreground": "#D0B344"}}]}
    },

And you will get the following:

Selected Release Notes

1.0.0

• The initial release of TDB Highlighter.

1.0.0 - 1.2.1

• Several user-requested features were added and some small bugs have been fixed.

CotEditor

• TDB Highlighter is now available for CotEditor as well! For details, please see this TDB Highlighter release.

Enjoy!