topas-editor extension

An extension to allow VS Code to work with TOPAS in a similar way to jEdit.
TOPAS_v7_Menus are essentially identical to the old jEdit setup. TOPAS_Durham menus are similar to jEdit, but somewhat simplified. There are new menus to change to TOPAS-specific colour schemes, and for some other common operations. This is a beta version, so use with care.

Quick installation guide

1. First install from VS Code market place by searching for "Topas Editor" and following the instructions. The "Commands" and "align-columns" extensions will be automatically installed at the same time.
2. In a VS Code window type "ctrl-shift-p" and start typing "Topas menu setup" then select and execute the command suggested.
3. Confirm you happy to install the TOPAS menus, then navigate and select the TOPAS directory.
4. You should then be able to see TOPAS menus by clicking on the "triangle in circle icon" on the left panel.

More detailed installation guide/information.

1. Install the topas-editor extension from the VS Code market place (click on the 3+1 small squares icon, type "topas editor" into the search dialog).
2. [OR, if you have a .vsix file downloaded (e.g. from github): In a VS Code window type shift-ctrl-p to bring up the command palette. Start typing "Extension install from vsix" then return. Navigate to find topas-editor-x.y.z.vsix on your computer and install.]
3. Either of these processes should also install the "Commands" extension from Alexander to support the TOPAS menus. If this doesn't happen, install Commands directly by clicking on the extensions icon (4+1 small squares) and typing "Commands" in the search window. It should appear as the top entry of three extensions with this name. The icon is a blue triange in a black circle with a blue outline. The full publisher.name is usernamehw.commands@1.14.1.
4. Set up the TOPAS menus for the Commands extension to access. In an VS Code window type shift-ctrl-p to bring up the command palette. Start typing "Topas menu setup" then select and execute the command suggested. C:\user\username\Appdata\Roaming\Code\User\settings.json should be automatically updated by adding the contents of johnsoevans\topas-editor\assets\topas-editor_settings.json . This could overwrite settings from other extensions, so a settings.json.backup file is created. You'll also be prompted to select the main TOPAS directory (which sets the TOPAS_DIR environment variable). If the setup doesn't work try one of the steps below. None of this has been fully tested.
5. When you click on Commands' "open triangle in circle" icon on the sidebar you should see TOPAS menus similar to jEdit menus on the left.
6. You should also see icons for the most common "Send to TOPAS", "Run TA (Academic)", "Run Bruker TOPAS" and "Run TC (command line version)" commands in the bottom status bar.
7. If you don't see the TOPAS menus, the setup may have failed and you need to set the TOPAS menus up by hand. Try:
   a. EITHER: Add the contents of topas-editor\assets\topas-editor_settings.json to C:\user\username\Appdata\Roaming\Code\User\settings.json. One way is to click on Commands' "arrow in circle" icon. Then click on the settings cog at the top. Then click on the blue text "Edit in settings.json" that appears in the main screen. Add the contents of topas-editor\assets\settings.json, taking care not to overwrite settings of other commands.
   b. OR: If you don't have any other extension settings in settings.json, you can directly copy topas-editor\assets\topas-editor_settings.json directly to C:\Users\username\AppData\Roaming\Code\User\settings.json.
8. If setting up the environment variable for TOPAS_DIR didn't work try one of the following (you'll get an error when you try and launch TA if it hasn't worked):
   a. If your menus are working properly go to the "VS Code+TOPAS commands" folder and click on "Set TOPAS directory".
   b. OR: in an editor window type "shift-ctrl-p" and start typing "Topas set directory".
   c. OR: on a Durham PC where user doesn't have admin privileges this can be done from a cmd.exe window run with elevated privileges. Type the command: setx TOPAS_DIR "D:\software\topasa_v7".
9. Three TOPAS themes have been defined (Light, Dark and Tech Ref). You can toggle between them and/or return to default themes from the "VS Code+TOPAS commands" menu or using ctrl-shift-p and theme selector.
10. You might also want to use the align-columns extension (jca02266.align-columns) when editting TOPAS INP files. It should be installed along with topas-editor. Select text then shift-ctrl-p align-columns.... Either align by a separator or using multiple cursors. If you e.g. align on beq sometimes an earlier space is removed; in this case align on " beq". Rylogic Text Aligner is also good for equations - it uses ctrl-alt-[ and ] to align/un-align automatically. It doesn't seem to work with spaces.
11. You can automatically update topas-editor whenever there is an update on the marketplace. The next time you start VS Code you'll be prompted to update TOPAS menus. If you want to do this instantly, click on "Update TOPAS menus" in the "VS CODE+TOPAS setup" folder. This will overwrite any changes you have made to the menus. You don't need to set the TOPAS directory each time, so click cancel when prompted.

Usage overview

topas-editor is designed to work with the "Commands" extension from Alexander to give jEdit like functionality to VS Code. "Commands" and a few other useful extensions should be auto-installed with topas-editor as listed in the package.json extensionDependencies.

Shortcut keys

You can run the most common TOPAS commands with short cut keys. Hold down ctrl then hit "t" for TOPAS followed by a second key:

• ctrl-ta: run TOPAS Academic
• ctrl-tb: run TOPAS Bruker
• ctrl-tc: run TC on the current INP file
• ctrl-tf: find INP file containing specific text
• ctrl-th: get help from the wiki
• ctrl-ti: insert str from CIF
• ctrl-tl: light/dark theme togle
• ctrl-ts: save and send INP file to TOPAS
• ctrl-tt: select a template file
• ctrl-tu: update TOPAS menus after topas-editor update
• ctrl-tx: make a date stamped archive of current INP file
• ctrl-t/: add/remove comment markers around current selection

The default TOPAS menus

Top level menus

• Send INP to TOPAS will save the current INP file and inform TOPAS to read from this file. A .backup is made at the same time.
• A single click on the "Run *" menus will run either the academic or commercial versions of TOPAS. a dialog window will tell you the software is launching.
• Run TC will execute the command line version of TOPAS. You can follow Rwp values in the terminal window. The .INP file gets automatically updated on convergence. A .backup file is made in case things go wrong.
• Archive INP file will create a time-stamped copy of the INP file.

TOPAS_Durham menus overview

These reproduce and extend the old jEdit menus. There are fewer submenus than previously as VS Code mankes it easier to unify writing of INP files.

TOPAS_Durham "Help"

• This subfolder contains links to various help pages.
• It also lets you load the various macro files (.inc) that contain TOPAS commands. Theseare useful for learning the TOPAS syntax and understanding some of the maths underlying fits.
• topas.log gets written every time TOPAS runs and contains the INP file in a more basic syntax. It's useful for debugging.

TOPAS_Durham "Rietveld or Pawley INP File"

If you click through these menus from top to bottom you can create a simple INP file for fitting.

• first click on "Select Data File" and navigate to select a data file in TOPAS supported format (.xy, .xye, .RAW, etc)
• Then select one of the instrument choices from the "Instrument Choices" folder
• Click any of the corrections you need to apply. In general you should refine either zero point or sample height but not both on a lab Bragg-Brentano instrument.
• In the "Rietveld or Pawley" folder click on one of the options for inputting a structure or for adding a Pawley phase. "Read from str or ISODISTORT" replaces the jEdit symmetry mode refinements menu.
• In the "Miscellaneous for str" folder choose any of the options needed.

TOPAS_Durham "Neutron tof", "Single crystal", "PDF fitting", "Indexing"

These folders let you access pre-written templates for different types of fitting. The files are read from the templates folder in your main TOPAS directory. You can also download templates via the "Prewritten Templates" menu if you don't have them. Once a file has been selected you have to save it as an appropriate name in a folder of your choosing (not the templates folder). You then have to remove any text following arrow (->) signs, which will be coloured purple by default.

TOPAS_Durham "Prewritten templates"

This folder lets you select a prewritten template. Once a file has been selected you have to save it as an appropriate name in a folder of your choosing (not the templates folder). You then have to remove any text following arrow (->) signs, which will be coloured purple by default. This is often the quickest way to set up more complex INP files. There is a menu for downloading templates from the TOPAS wiki.

TOPAS_Durham "Simulate pattern"

This menau lets you select a .CIF file and will simulate a Cu Ka2 data set. Edit the INP file directly for other simulations.

TOPAS_Durham "Topas examples"

The commands in this submenu let you find example INP files for inspiration.

• "Search all examples for text string" lets you type in any phrase. It will then search the TOPAS examples for INP files with that string in their filename or contents. For example if you type "stack" you will get various INP files for stacking fault refinements. The search could take a few seconds to complete.
• All examples gives a full list of example inp files that you can select from.
• The other options list the INP files in various subfolders in "test_examples" of your main TOPAS directory.

TOPAS_Durham "Miscellaneous useful commands"

Contains what you might expect from the title!

• Most commands should be self explanatory
• "Cu Kb and W Ka contamination" adds lines to the emission profile for these radiations. Cu Kbeta is common when using a psd detector as Ni filter doesn't remove all radiation. W Kalpha is common on old tubes due to deposition of the filament material on the Cu or Mo target.

TOPAS_v7_Menus

This is reproduced from jEdit. It contains a list of clickable TOPAS commands organised by INP file scope.

TOpyAS

Somewhere to store commands to run python routines that are part of your TOPAS workflow. For example there is a link to run Matthew Rowles' pdCIFplotter if you have it installed.

VS Code+TOPAS commands

Some VS Code commands that are useful with TOPAS.

• Set a light or dark TOPAS colour scheme, each click toggles the theme.
• Set a colour scheme to match TOPAS technical reference
• Revert to standard VS Code Light+ or Dark+, each click toggles the theme.
• "Remove esd's from file" will strip out topas `_0.001 type information from the file
• "Toggle comment block on-off /../" will put highlighted text into a TOPAS /.../ comment block, or remove the comment markers if it's already commented.
• Folding commands to make VS Code folds on topas '{{{ '}}} and #ifdef #endif markup, in addition to standard things.
• Save commands.
• Update commands.

VS Code+TOPAS setup

• Set the TOPAS directory environment variable. This should be a permanent change, but I sometimes find it reverts to earlier values.
• Menus won't get automatically updated when topas-editor updates, but you are normally prompted to update them. When this happens you have three options: update, never, later. If you select "later" you will be prompted to update everytime VS Code starts. If you click "never" you won't be asked again until topas-editor is updated.
• Update topas menus lets you update menus even if you clicked "never" in the previous option.
• If you reset your menu flag to 0.0.0 you'll be asked about updating next time VS Code starts

Common tips and tricks

These are some useful tricks.

• If you want to auto-align text for column editing then select the text and type shift-ctrl-P then start typing align. Select "align mulitiple columns by separator". Type in a space.
• Select a column of text with "shift-alt-click". Hit esc to go back to normal cursor editting.
• VS Code doesn't have jEdit's ability to select beyond the end of a line. If there is an extension for this let me know.

topas-editor VS Code commands/features

Various TOPAS-related commands are created either in menus or via VS Code commands:

• TopasSetupMenus.ts: Will try and set up TOPAS menus from your latest topas-editor installation
• TopaSaveSet.ts: Sends current INP file to TOPAS by writing to launch_file.txt in your main TOPAS directory
• TopasArchive.ts creates a timestamped copy of filename_YYYY-mm-dd-hhmm.INP (or any other extension)
• TopasCreateInpFile.ts: Will make an INP file via the Durham menus
• TopasImportCIF: Will run cif1.exe and insert temp.str
• TopasInsertStructure.ts: Allows user to insert a basic structure via prompts
• TopasInpFromTemplate.ts: Will load a template file and prompt you to save to new filename
• TopasInsertFileTextArg.ts: Does various insertions depending on arguments passed
• TopasOpenExamples.ts: Allows user to select from different TOPAS example files
• TopasSearchINP.ts will look through example input files for a search string and open them
• TopasSimulateFromCIF.ts: Like TopasImportCIF but sets up a logical filename for the INP
• TopasFold.ts: Will fold on the jEdit style '{{{ ... '}}} brackets and topas #ifdef ... #endif type syntax
• TopasResetVersion.ts: Sets the menus version to 0.0.0. Used for testing updates.
• TopasRemoveEsds.ts: Removes esds from refined values without having to rerun the file
• TopesToggleComment.ts: Adds or removes /* */ markers round highlighted text
• There's a simple syntaxes file defining INP syntax and three themes "Topas Light", "Topas Dark" and "Topas TechRef" are defined
• VS Code+TOPAS setup menu lets you update menus after updating the extension
• Run TA or TOPAS commercial from the side menus or status bar at the bottom
• Run tc.exe directly on the current INP file and update the INP file being edited

Contributing

Contributions from johnsoevans, JamesDoingStuff, Keeble, PAChater.

FAQ

1. The commands "triangle in circle" has disappeared from the left bar and I can't see TOPAS menus.

• Type ctrl-shift-P then type "View reset view locations". It should return.

2. Next question.

• answer