mxg

MESMER XML GUI (MXG)

Introduction

MESMER XML GUI (MXG) is a Graphical User Interface (GUI) for generating and visualising Master Equation Solver for Multi Energy-well Reactions (MESMER) XML format data.

EPSRC funded MXG development in 2024.

MXG can be used via GitHub Pages and can be installed onto devices as a Progressive Web Application (PWA) that can be used offline. Version 0.16 is served from GitHub Pages from where the respective PWA can be installed:

• Version 0.16
• Version 0.15

A PWA is a type of application software delivered via the Web and built using common Web technologies including HTML, CSS, JavaScript, and WebAssembly. It should work on any platform with a standards-compliant browser. For more details about what a PWA is please see:

• Wikipedia Progressive Web App Article
• https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps

PWA installation varies by Web browser/device:

• General instructions
• Specific instructions for Chrome, Firefox, Edge, Safari.

MXG is built, packaged and deployed using Node and Parcel. The main source code is TypeScript. There are also JSON configuration files and a Web Worker JavaScript file.

MXG uses 3DMol.js under a BSD-3-Clause licence to visualise molecules with coordinates. For details of 3DMol.js please see the GitHub repository: https://github.com/3dmol/3Dmol.js. If you use the 3DMol.js visualisations, please cite: Nicholas Rego and David Koes 3Dmol.js: molecular visualization with WebGL Bioinformatics (2015) 31 (8): 1322-1324 doi:10.1093/bioinformatics/btu829.

MXG uses Big.js under an MIT licence to handle decimal numbers. For details of Big.js please see the GitHub repository: https://mikemcl.github.io/big.js/.

User/Contributor Guide

• MXG is for preparing MESMER input data, and visualising and reformulating MESMER output data.
• Please check MESMER input data created by MXG, especially before executing expensive MESMER calculations.
• MXG has no undo button, so please take care to save your work in MXG periodically. You should be able to reload a saved file.
• Please test MXG and report and comment on issues to help develop MXG. To report an issue you will need a GitHub account. Please follow this link to check for issues and report them.
• Submitted issues that are feature requests may help form development plans for future major versions.

There is a Developer Guide below with set up instructions. To contribute code, please use the following workflow:

1. Fork the repository.
2. Create and comment on an issue to let others know you are working on it.
3. Test changes to your fork.
4. Submit a pull request linking to the issue.

Development Plans

• Version 1.0
  • There is no fixed timeline for completing testing and releasing Version 1.0. Version 0.16 is the latest beta test version.

Developer Guide

• This section is a guide to compiling and deploying a new versions of MXG, and provides some trouble shooting hints.
• Microsoft Visual Studio Code is suggested as a development environment.
• To make it easier to release new versions and deploy to different places, some key variables are stored in the .env file. These are used in the configure step to create build files that are duplicate of source files, but with variable values replaced. Take care to edit the source files and not those generated from these. The configure.js file file shows the source and generated file paths of those files that are configured.

Set Up

• Install the latest LTS release of Node
  • Current development is tested with Node 22.10.1
• Fork and clone this repository.
• cd into the repository
• Install dependencies: npm install
  • This can take a few minutes.

Compile

• To compile (transpile using the installed typescript Node Package) run: npm run compile

Build/Package

• To build (using the installed parcel Node Package) run: npm run build

Launch

• To launch (using the installed npx Node Package) run: npm run start
• A Web server should run on the local host on port 3460: localhost:3460/

To release a new version

1. Update the version number in .env.
2. Delete the node_modules directory.
3. Re-install dependencies (run npm install).
4. Re-configure (run npm run configure).
5. Re-compile (run npm run compile).
6. Re-build (run npm run build).
7. Re-launch (run npm run start).
8. Test (load a MESMER input file, create a MESMER input file from scratch, load a MESMER output file).
9. Commit changes.
10. Create pull request.
11. Merge pull request.
12. Check deployment on GitHub Pages.
13. Check PWA installation.

Trouble Shooting Guide

1. Open the Web browser developer console and check for error and warning messages.
2. If the Service Worker is not registering, delete the .parcel-cache directory, and re-launch using npm run start.
3. Delete the Web browser cache and try again.
4. Try deleting the node_modules directory, re-install dependencies npm install, re-build npm run build, and re-launch npm run start.
5. If the problem persists, please report it to the community as an issue.

This site is open source. Improve this page.