topas-editor extension

topas-editor allows VS Code to interact 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 those in jEdit, but somewhat simplified. There are new menus to change to TOPAS-friendly colour schemes, and for some other common operations.
Commands are all available in the side panel. The most common commands also have a ctrl-t* shortcut key assigned, are in the right-click menu, and/or in the status bar at the bottom of the editor.
This is a beta version, so use with care.

Quick installation guide

1. First install topas-editor 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-t ctrl-u. Alternatively 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 if prompted to do so.
4. You should then be able to see TOPAS menus by clicking on the "triangle in circle icon" on the left panel.
5. You might like to install the indent-rainbow extension to make viewing nicely indented INP files easier.

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/menus

You can run the most common TOPAS commands with short cut keys. Some are also available via a right-click. 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-td: add or remove horizontal markers for xdd and str sections
• ctrl-tf: find INP file containing specific text
• ctrl-th: toggle hover help on/off
• ctrl-ti: insert str from CIF
• ctrl-tl: light/dark theme toggle
• ctrl-to: open .OUT file corresponding to current .INP
• ctrl-tr: remove ` backtick refined markers from file
• 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-tw: get help from the wiki
• ctrl-t/: add/remove comment markers around current selection
• shift-ctrl-f: does the equivalent of the jEdit alt-. hypersearch

The default TOPAS menus

Top level menus

• Topas-editor help shows a quick help guide
• 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. TA and topas.exe both run in windows high priority mode.
• 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. TC runs in windows normal priority mode.
• Archive INP file will create a time-stamped copy of the INP file.

Help/General/Links

• This subfolder contains links to various help pages.
• It also lets you load the various macro files (.inc) that contain TOPAS commands. These are 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 menus overview

These reproduce and extend the old jEdit menus. There are fewer submenus than previously as VS Code makes it easier to unify menus.

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 topas-editor assets 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. The template folder will be somewhere on your computer like C:\Users\username.vscode\extensions\johnsoevans.topas-editor-n.m.p\assets\templates.

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 new 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
• "Insert output lines automatically" attempts to insert instructions to create an output file called 'results.txt' with all named parameters with headings on the columns. You need do_errors on to create a correlation matrix with parameter names. Any name with 8 consecutive hexadecimal characters is presumed to be auto-created by TOPAS so not output. If this is a problem use short parameter names! It works with #list so presumes you have set up the xdd dataset as "filename" and are using a Run_Number. With this format all parameters with esds can be plotted from a trivial Python script.
• "Refine atoms (with min/max)" will take the higlighted site lines and introduce macros with named parameters for x, y and z and min/max values for how far atoms can move. This is a good way to start a refinement, and lets you reset coordinates that wander (by setting max_shift limit to +/- 0 from ideal). It sets one beq per atom type and tries to retain any occupancy information in the file. You have to set which parameters can be refined with "!" flags where needed. Each site needs to have a unique name. For coordinates like 0.3333 you need to use =1/3;. It should cope with coordinates expressed as equations or with refinement flags. This hasn't been extensively tested so use with care.
• "Refine beq by site type" will put an equated beq value on each atom of the same occupancy type
• "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 the 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.

• "Plot refinement results" will copy plot_all.py to your directory and try and plot a file called "results.txt" using Run_Number as the x-axis. If you've done a standard analysis using John's filename conventions you should get plots of all parameters with esd's on the screen. If it fails you have the python script to edit.

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. You should be prompted to set the TOPAS directory if it is unset; this isn't fully tested.
• Update topas menus lets you update menus even if you clicked "never" in the previous option.
• Add my menus lets you (re)install personal menus (see below).
• Show topas-editor paths and settings will pop up a message windoow giving the topas directory (TOPAS_DIR) and your topas-editor storage folders.
• If you reset your menu flag to 0.0.0 you'll be asked about updating next time VS Code starts
• Hover help on/off toggle will turn the pop up help when you hover over a word on/off
• Hover help update will reprocess hovertext_help.md to update hoverhelp
• "Toggle horizontal xdd/str markers" will put horizontal lines to separte xdd and str type sections. xdd level gets a solid line and str/hkl_Is/xo_Is get a dashed line.

Custom menus - My Menus

This is where you can add your own TOPAS commands. You can edit the commands directly in settings.json by right clicking on the menu and selecting "reveal in settings.json". However these commands will get overwritten every time you update topas-editor menus. You should therefore store them in a file called something line "my_menus.json". After every menu update run the command "Add my menus" to reinstall them. There's an example menu file in the topas-editor assets folder. It will be somewhere like: C:\Users\username.vscode\extensions\johnsoevans.topas-editor-1.0.13\assets. This is completely untested!

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)
• TopasBeqByType.ts sets one beq per atomic type on highlighted atoms
• TopasCreateInpFile.ts: Will make an INP file via the Durham menus
• TopasFold.ts: Will fold on the jEdit style '{{{ ... '}}} brackets, topas #ifdef ... #endif type syntax and macros with a single {} in them
• TopasHelp.ts displays topas-editor help
• TopasHoverHelp.ts sets up hoverhelp to read from hovertext_help.md
• 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
• TopasMenuSetup.ts: Installs menus and checks if TOPAS directory set
• TopasOpenExamples.ts: Allows user to select from different TOPAS example files
• TopasOpenOut.ts: Opens the .out file corresponding to .inp being editted
• TopasOutputLInes.ts: Gets parameter names without 8 hexadecimal characters from correlation matrix and creates ouput lines
• TopasPlotAllPy.ts: Copies plot_all.py from assets directory to working directory and tries to run it
• TopasReadHoverHelp.ts: Opens hoverhelp_text.md to show all hints
• TopasRefineAtoms.ts: If you highlight atomic coordinates they and select command they will get rewritten to refne with min/max values around original
• TopasRemoveEsds.ts: Strips out '_0.001354 esds from INP file
• TopasRemoveRefinedMarkers.ts: Strips out ' strings which mark numbers as refined
• TopasResetVersion.ts: Sets the menus version to 0.0.0. Used for testing updates.
• 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
• TopesToggleComment.ts: Adds or removes /* */ markers round highlighted text
• TopesToggleDecoration.ts: Adds or removes horizontal markers before xdd and str lines
• 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

More detailed installation guide/information.

1. This information shouldn't be needed now as most set up is automated. It's retained in case people have problems.
2. 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).
3. [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.]
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. The environment variable TOPAS_DIR should be set when you install menus and reloaded every time you run VS Code. If it 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. 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: as a last resort you can set up a system environment variable, but this will need changing manually if you change your topas directory. 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". Use the "Show topas-editor paths and settings" command in "VS Code+TOPAS setup" folder to check your settings.
10. 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.
11. 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.
12. 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. It's safest to reset the TOPAS directory each time.

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