topas-editor Extension
Some commands 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, but somewhat simplified. There are also 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
- Download from VS Code market place - search for "Topas Editor". The "Commands" and "align-columsn" extensions will be automatically installed at the same time.
- In a VS Code window type "ctrl-shift-p" and start typing "Topas menu setup" then select and execute the command.
- Confirm you happy to install the menus, then navigate and select the TOPAS directory.
- You should be able to see TOPAS menus by clicking on the "triangle in circle icon" on the left.
More detailed installation guide.
- Install the topas-editor extension from the VS Code market place (click on the 3+1 small squares icon, type "topas" into the search window).
- [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.]
- 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.
- 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. 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 is made. 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 properly tested.
- When you click on Commands' "open triangle in circle" icon on the sidebar you should see TOPAS menus similar to jEdit menus.
- You should also see icons for the most common "Send to TOPAS", "Launch TOPAS" and "Run TC" commands in the bottom status bar.
- 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.
- If setting up the environment variable for TOPAS_DIR didn't work try one of the following (you'll get an error e.g. when you try and launch TA):
a. If your menus are working properly go to the "VS Code+TOPAS commands" folder and click on "Set TOPAS directory".
b. OR: in a 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_v8".
- Two TOPAS themes have been defined (Light and Dark). 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.
- You might also want to use the align-columns extension (jca02266.align-columns) to work with 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 by multiple cursors. If you e.g. align on beq sometimes an earlier space is removed; in this case align on " beq". Rylogic Text Algnier is also good for equations - it uses ctrl-alt-[ and ] to align/un-align autmatically. It doesn't seem to work with spaces.
- When topas-editor is updated you will need to update menus by hand. The quickets way is to 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 change the TOPAS directory each time.
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 it's listed in the package.json extensionDependencies.
- 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 "Launch" menus will launch either the academic or commercial versions of TOPAS.
- Run TC will execute the command line version of TOPAS. You can follow Rwp values in the terminal. 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
These reproduce the old jEdit menus. There are fewer submenus than previously as VS Code mankes it ieasier to simplify things.
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 which are useful for learning the syntax.
- 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.
- first click on "Select Data File" and navigate to select a 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 instrumnet.
- In the "Rietveld or Pawley" folder click on one of the three options
- 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 folder. You can download tempates from the "Prewritten Templates" folder. 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 templated. 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 menus 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.
TOPAS_Durham "Topas examples"
The commands in this menu 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
- Other options search various subbolders in "test_examples" of your main TOPAS directory.
TOPAS_Durham "Miscellaneous useful commands"
Contains what you might expect from the title!
This is reproduced from jEdit. It contains a list of clickable TOPAS commands organised by scope.
TOpyAS
Somewhere to store python routines that are part of your TOPAS workflow. For example there is a link to run Matthew Rowles' pdCIFplotter.
VS Code+TOPAS commands
Some VS Code commands that are useful with TOPAS.
- Set a light or dark TOPAS colour scheme, each click toggles theme
- Revert to standard VS Code Light+ or Dark+, each click toggles theme
- Folding commands VS Code folds on topas '{{{ '}}} and #ifdef #endif in addition to standard things.
- Save commands
- Update commands
VS Code+TOPAS setup
- Set the TOPAS directory environment variable
- Menus don't get automatically updated when topas-editor updates, but you are nomrally 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 autoalign 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.
- 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.
Some VS Code commands/features
Various TOPAS-related commands are created either in menus or via VS Code commands:
- TopasSetupMenus.ts: Will try and setup TOPAS menus from your latest topas-editor installation
- TopaSaveSet.ts: Sends current INP file to TOPAs via launch_file.txt
- Launch TA or TOPAS commercial
- Run tc.exe directly on the current INP file
- TopasArchive.ts creates a timestamped copy of filename_YYYY-mm-dd-hhmm.INP (or anyt 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: 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 like TopasImportCIF but sets up filename for INP
- There's a simple syntaxes file defining INP syntax and two themes "Topas Light" and "Topas Dark" defined
- TopasFold.ts: Will fold on the jEdit style '{{{ ... '}}} brackets and topas #ifdef ... #endif type syntax
- TopasResetVersion - sets the menus version to 0.0.0. Used for testing updates.
- VS Code+TOPAS setup menu lets you update menus after updating the extension
Contributing
Contributions from JamesDoingStuff, Keeble, PAChater, johnsoevans.
FAQ
- The commands "triangle in circle" has disappeared from the right bar and I can't see TOPAS menus.
- Type ctrl-shift-P then type "View reset view locations". It should return.
- Next question.
