General
*******


Introduction
============

This document will provide background information for the Graphical
User Interface, part of the AMS package.

The purpose of this document is to give more detailed background
information on how the GUI operates. It will not explain how to use it
in detail. For that reason, we strongly suggest that before reading
this document, you first check the GUI tutorials.


Release 2026.1
==============

* General:

  * Bond Orders menu in Properties menu to view the bond orders
    resulting from a calculation.

  * Coordination number now available in Atom Properties.

  * All GUI modules should remember their size and position on screen.

  * All GUI modules showing periodic systems: View -> View Direction
    now also has option to view along lattice vectors.

  * Mouse As Joystick: now keeps on rotating until extra click in
    space.

  * Some menus have been reorganzied to avoid very long menus. In
    particular many options from the View menu now live in the
    Properties menu.

  * All graphs: option to specify the formatting of the values along
    the axes via the dialog you get by double clicking on an axes.

* AMSbands:

  * Option to show all K-points in the Brillouin Zone (Show K Points
    in the View -> Brillouin Zone menu).

  * Option to show the K-point labels (Show K Points) has been renamed
    to Show Labels, in the Brillouin Zone menu.

* AMSinput:

  * Builder (now Builders -> Packed Molecules): allow N mols for one
    component to be empty. This makes it easier to pack dilute
    solutions without specifying the number of solvent molecules.

  * Nanoparticle Builder

  * Nanotube Builder

  * (Experimental) Slab BuildeR

  * Builder menus reorganized (in AMSinput Builder), Builder has been
    renamed to Packed Molecules.

  * Builders -> Microsolvation Builder (previously called Solvent
    Molecules) interface adjusted to match the other builders.

  * Improve reading of run scripts / input.

  * Set Origin and Set Center Of Mass options in the Edit menu now
    optionally adjust only the X, Y or Z coordinate.

  * Optimize button (the cog-wheel in the toolbar) is now also
    available for periodic systems.

  * Show coordination number (CN) at bottom when a single atom is
    selected.

  * Support Hybrid engine PBC option for energy terms.

  * Support QE Magnetic Anitrosopy Energy.

  * When saving a job and results are present, Save As is
    automatically used to prevent overwriting results.

  * When saving a job that is restarting from its own results,
    overwriting itself is blocked (even if the user tries to do that
    via the Save As dialog).

  * PES scan: support scan without optimization.

  * No more dialog after a calculation to update results, instead a
    prominent 'Update molecule' button.

  * Forcefield has now an Atom Typing task, and the buttons to guess
    atom types now use the same atom typing tool.

* AMSview:

  * Interface reworked: instead of a line on the bottom with controls
    now the controls are on the right side of the window. The size of
    the right hand panel can be controlled by the user (like in
    AMSinput), and in the View menu there are some commands to
    hide/show the right side, or to go back to the default.

  * Add Potential shortcut in Properties.

  * Add button bar with shortcuts for Add menu and some items from the
    Properties menu.

  * Renamed some menu items: Cut Plane -> Plane, IsoSurface: Multi ->
    IsoSurface: Multiple.

  * Menu items for handling bonds have moved from the Add menu to the
    Edit menu.

  * For IsoSurface: Multiple visualizations a clip plane is
    automatically used.

  * Default iso values now are set only when changing the type of
    field. Thus switching between orbitals for example will use
    whatever you changed.

  * In the Preferences module you can set the default iso value to
    use.

  * Atom properties that are showing (via Properties -> Atom Info)
    for selected atoms are summed and shown at the right bottom.

  * Make it easier to calculate fields remotely via AMSjobs queue
    selection in the Fields menu (it was already available via the
    popup that showed when calculating a field).

  * Save the AMSjobs queue selected to calculate fields. Normally this
    is ignored unless you turn on the option in AMSpreferences to use
    it.

  * Planes now have easier controls to position them, and the initial
    positioning is based on the molecule.

  * Improve multiple files handling, sort IRC results to make sure
    they are in proper order, open IRC result files automatically when
    opening IRC AMS job.

  * Open now automatically uses New first, use File -> Add to open
    results from another calculation and add it to the current set of
    results.

  * Save movies of multiple geometries frames, like running through
    IRC steps.

  * When using the HOMO/LUMO shortcuts, or the 'Copy to all
    geometries' option in the details, AMSview will try to swap colors
    of real orbitals to visually match them with the previous point.
    This is based on the images on screen, so if it fails try
    reorienting or zooming in and use 'Copy to all geometries' again.

* AMSmovie:

  * Some menus have been reorganzied (Graph, View, Properties) to
    avoid very long menus.

* AMSjobs:

  * The queue of jobs waiting to run on the local machine is now
    persistent (saved to disk). This should avoid issues with jobs
    having a queued status but never starting to run.

  * Filter: add option to turn all on or off.

  * Select a .run file, use SCM menu Input (or right click Input) to
    open the .run script in AMSinput

  * Prevent scmjobd processes for local jobs by setting the
    SCM_NO_SCMJOBD_FOR_LOCAL_JOBS env var. You should not use this
    feature as smcjobd does useful things like informing amsinput and
    params that a job is ready, handling error output etc. It does
    reduce the number of processes spawned by AMSjobs.


Release 2025.1
==============

* General:

  * Open JupyterLab notebooks (.ipynb files) via SCM menu

  * License Info showing the dirac check output in the Help menu

  * Command to start Terminal on a Mac now directly sets the
    environment (no need to copy/paste it any more)

  * Improved display of coordinate axes, now showing at origin and /or
    in the left-bottom corner. The choice (in the View menu) will be
    remembered.

  * Improved display of lattice vectors: added an option to change the
    thickness (in the View Periodic menu). THe choice will be
    remembered.

* AMSjobs:

  * Open JupyterLab notebooks (.ipynb files) by clicking on them in
    the AMSjobs window

  * Run Jupyterlab notebooks without GUI either locally or remote
    (like any other job), results in the .results folder

  * Add # dependency lines to your ipynb notebook file to use a
    dependency (like the dependency lines in the AMS run scripts)

  * Editing a queue in AMSjobs now has a Save As... option

* AMSinput:

  * Editing of the main pages for the engines is no longer possible

  * Startup much faster

  * Back and forward buttons on panels (arrows on the top left of the
    panels)

  * Input options panel (the right half of the AMSinput window)
    resizable and improved dynamic layout with font changes

  * Menu commands with shortcuts to adjust layout: Molecule only,
    Input options only, or both

  * Arrow up and down jump to previous/next non-default item in Expert
    panels

  * ROKS support

  * ROSE support

  * ASE calculators: option to analyze a selected calculator .py file,
    and use the defaults if desired.

  * QE work function support.

  * QE interface now supports slabs and chains as wel.

  * Builder now uses packmol via the python packmol implementation,
    the GUI for this has changed.

  * Region manipulation now also part of the undo stack.

  * Support analytical phonons with QE.

  * Support CREST metadynamics.

  * Support PLUMED.

* AMSmovie:

  * MD Analysis: support setting charges and masses per atom for MSD.

  * MD molecule counts: now also try to use Time on the horizontal
    axes, if 'Try To Use Time On X-axes' is checked in the Graph menu.

* ParAMS GUI:

  * Back and forward buttons on panels (arrows on the top left of the
    panels).

  * SCM_PARAMS_RESULTS_ONLY_SIZE env var: if input file size bigger
    than this value, offer to load results only (for speed). A value
    of 0 is the same as not setting it (and thus always loading the
    input).

  * Save the Reference or ParAMS run script for selected jobs. The run
    scripts can be opened by AMSinput.

* KFBrowser:

  * Plots in the ams.rkf Plot section now are available in the non-
    expert mode as plots.


Release 2024.1
==============

This release no longer supports old style ReaxFF input and output (the
non-AMS version with the .rxkf result files). This release only
supports QE via AMS, the old QE interface has been removed.

In comparison to AMS-GUI 2023.1, the 2024.1 release offers many bug
fixes and the following new changes or main functionality:

* General:

  * Show Info: Axes And Planes menu in View menu (if present): show
    info about the vector defined by selecting 2 atoms:

    * length of vector

    * angle with x, y and z-axis

    * projection on x, y and z-axis

    * also angle and projection on user defined vector and user
      defined plane (user specifies normal vector)

    * for periodic systems, similar info for angles and projections on
      the lattice vectors

    * for periodic systems, also show result using shortest image
      convention

  * In Show Info view: pin information so more info can be seen at the
    same time.

  * The Show Info view will update in AMSmovie when playing a movie.

* AMSjobs:

  * Command to copy paths for local or remote jobs, in the Jobs menu,
    so they can easily be used in a terminal.

* AMSinput:

  * Export a job to a PLAMS Python script (only applicable to single
    AMS jobs, not more complicated tasks like COSMO-RS Compound or
    Conformers).

  * No longer supports opening old style ReaxFF input (the non-AMS
    version)

  * SCRF support removed (as ADF no longer supports it)

  * Support QE engine (instead of the old non-engine QE)

  * Improved selection of ReaxFF force fields (note double click in
    table is easiest to use)

  * Support reaxff.charges option to define charge per atom (edit in
    AtomDetails).

  * Support defining TS reaction coordinate using an initial and final
    system

  * Support Repulsion engine add-on

  * DFTB Single Point more button links to Fragment panel

  * Builder now puts new molecules in region Builder instead of the
    confusing Auto_Generated region

  * Import molecule(s) from file(s): use filename or formula as name
    of the imported molecule (if importing into an empty molecule
    space). Note the molecule name is visible only when multiple
    molecules are present (via Edit -> New Molecule for example, or
    when importing multiple files.).

  * Import molecules from files: now you can select multiple files to
    be imported at the same time, each in its own molecule space.

  * Import molecule using SMILES: import multiple SMILES (separated by
    spaces) as multiple molecule. And use SMILES or formula as name of
    the imported molecule (if importing into an empty molecule space).
    Note the molecule name is visible only when multiple molecules are
    present (via edit -> New Molecule for example, or when using
    multiple SMILESs).

  * Import molecule from a forcefield.rkf file: read forcefield types,
    charges and patch file as well

  * Use LoadSystem key via Coordinates panel

  * When showing multiple molecules in a grid, clicking in an empty
    grid space will create a new molecule

  * Powder X-Ray Diffraction (XRD) available from the View menu.
    Before AMS2026, this requires additional installation of pymatgen
    from SCM → Packages.

  * Delete All Molecules: same as New, but only for the molecules
    (leaves the changed settings intact)

  * Add TSRC distance term using a dummy atom

  * BAND restart DOS and band structure support

  * Paste multiple values in Atom details fields: depending on number
    of pasted values update all atoms in atom selection (also make
    sure current field is in selection), all atoms, or only current
    field.

  * Improve reading of run scripts (especially picking up input
    options for non-unique keys)

  * Paste engine block only (starting with Engine and ending with
    EndEngine)

  * Import Engine Settings (similar to pasting the engine block only),
    from .run scripts, ams.rkf (the userinput variable is used), or
    engine.txt as made by params. Intended use is with MD Active
    Learning, to use the resulting engine after training in another
    job (just use Import Engine Settings and select the ams.rkf file
    from the active learning job). The command lives in the File menu.

  * When using LoadEngine, switch to a dummy LoadEngine module to make
    it clear for the user and to prevent engine settings to be
    changed. LoadEngine could be used when importing a run script that
    is using it.

  * Offer to try to read run script when pasting an AMS job script
    (recognized by something like ams << eor and matching eor at end
    of input, as in all example run scripts and run scripts made by
    AMSinput)

  * Support MD Reaction Boost

  * MD Active Learning module (which is Simple Active Learning), see
    also Import Engine Settings

  * Support pNMR

  * Perturb atoms randomly by 0.01 Angstrom via the Edit→Perturb
    option.

  * Undo/Redo work only on the molecule structure, and now also only
    when the focus is on that panel, thus while editing the molecule
    or after clicking in it, and NOT when editing input options.

* AMSmovie:

  * PES Scans: improve labels below molecule

  * PES Scans: option to reorder all frames by PES points, useful if
    some PES points are redone at the end

  * No longer support .rxkf files

  * Analysis MSD supports properties, making it possible to compute
    ionic conductivity

  * Active learning trajectories: in File -> Related Files the
    trajectories of related trajectories are available
    (stepX_attempt_Y_simulation, and final simulation).

* AMSview:

  * NCI diagram support for ADF results

  * Improve ease of positioning planes (contour planes and colored
    planes), via explicit setting of normal vectors and a point on the
    plane

  * Add visualization along a line: the values of the field, and these
    values integrated along the line. The resulting line graph may be
    saved as image or as XY values.

  * Add visualization along a line: now also the values integrated
    over a plane perpendicular to the line, and these may also be
    integrated over the line (thus integrating 3D space);

  * Add special Grid Cell that covers at least one cell spanned by the
    lattice vectors (offset to match the cell as shown by AMSview).

* AMSspectra:

  * NMR: support visualization of pNMR results

* AMSdos:

  * Support display of DOS info from QE using QE as AMS engine, older
    QE stuff no longer supported.

* AMSbands:

  * Support display of DOS and BAND structure info from QE using QE as
    AMS engine, older QE stuff no longer supported.

* ParAMS GUI:

  * Improved selection of ReaxFF force fields

  * Generate validation set now by JobID as an option

  * Option to load a paramter (interface) yaml file (it will replace
    any paramter data already loaded).

  * Support Machine Learning training, input and visualization

  * When opening a MD Active Learning job (simple active learning) the
    last training result will be shown.

  * Option to open AMSinput with an engine with training results
    (based on the engine.txt files)


Release 2023.1
==============

In comparison to AMS-GUI 2022.1, the 2023.1 release offers many bug
fixes and the following new main functionality:

* General:

  * Two new periodic view options are added. The three available
    options are now:

    * (old) Repeat unit cells

    * (new) A layer of x (default = 2.0) Angstrom around the unit cell

    * (new) Complete the molecules that are partially inside the unit
      cell

  * The 2.0 Angstrom layer is the new periodic view default, and the
    periodic display threshold was increased.

  * New atom selection methods are added

    * Select atoms by index

    * Select atoms with an interactive box widget and box parameters

    * Select atoms by region

* AMSjobs:

  * Apply to all check when doing something to multiple jobs

  * Report to tsv file now always includes filename from which results
    are collected

* AMSinput:

  * Presets have been changed: check the documentation for details.

  * Builder supports explicit bonds from .in files

  * ACE Reaction Network support

  * ASE engine support

  * Improve import of job from run scripts

  * Show molecule formula per region on Regions panel

  * Sort coordinate table by coordinate or element type

  * PES scan per x/y/z coordinate supported

  * Multiple NEB intermediates

  * Dynamic factors in hybrid engine

  * MD reactor (Martinez nanoreactor)

  * GW for BAND

  * MP2, RPA and double hybrids for BAND

  * Conformers support, both generating conformers and using
    conformers with further calculations using the conformers.rkf file

  * MD analysis jobs supported as part of the main job

  * MD analysis: automatically run over all elements for RDF and ACF
    if requested

  * Save As: menu shortcut

  * Preoptimizer now optionally honors constraints

* AMSmovie:

  * The graphs use now Time on the X-axis instead of Frame, if Time is
    available for plotting (as in MD results)

  * Analysis of MD trajectories now remember settings and shows last
    result, if present

  * Analysis: multiple calculations for one trajectory of same type
    (multiple RDF etc) now supported

  * Analysis: calculated the RDF/ACF/MSD/Histogram in a separate job,
    possibly on some remote system

  * ACE reaction support

  * ChemTraYzer2 support: handle the molecule population and event
    files, producing graphs in addition to the tables

* AMSspectra:

  * Support Conformers via amsbatch.rkf

  * Support BAND GW

* AMSbands:

  * Option to shift the Fermi energy to zero.

* AMSdos:

  * Use stacked curves for the partial DOS (similar to the DOS in
    AMSbands).

  * Option to shift the Fermi energy to zero.

  * Option to mirror beta dos.

* AMSkinetics:

  * Import PES Exploration binding sites result to obtain a complete
    Zacros system setup

* AMSview:

  * Visualization of atom vector properties

  * Visualization of NBO natural charges

  * Visualization of RISM Guv RDF

* AMSoutput:

  * Added some DFTB menu shortcuts

  * Added generic Header menu with shortcuts to all headers (any text
    between bars)

* ParAMS GUI:

  * GLOMPO support

  * GUI to set up the job options (in the Settings tab)


Release 2022.1
==============

In comparison to AMS-GUI 2021.1, the 2022.1 release offers many bug
fixes and the following new main functionality:

* General:

  * All GUI modules transfer job to ParAMS GUI via menu command
    (cmd/ctrl-T)

  * (Linux only) Better dependency handling. Incompatible libraries
    from $AMSBIN/lib no longer need to be removed.

  * (Windows only) Option to use a different method of GUI inter-
    communication. The default uses sockets that can be blocked by
    security software. Set the environment variable SCM_SCMD_PIPE to
    use the new alternative that uses named pipes.

* AMSinput:

  * Open .run files (also importing many options)

  * Import system block from .run files

  * Open and export system block (as in run scripts) as .in files

  * AMS Lattice scan

  * GFNFF engine

  * Lennard-Jones engine

  * APPLE&P Force Field type

  * FCF support updated

  * GW support updated

  * DFTB fragments

  * QTAIM / IQA support updated

  * FQFMu forcefield for FQQM.

  * FQQM and FDE combination

  * Workflows target with OLED tasks

  * Region constraints

  * Constraint for all bonded pairs in selection

  * Constraints work with shortest PBC distance

  * Conceptual DFT / Fukui improvements by Laurent Joubert

  * Autografs update SBU database

  * Single Point option for COSMO-RS compound

  * Crystal slicer automatically converts to conventional cell and
    aligns axes

* AMSjobs:

  * Better support for running PLAMS jobs

  * Improved queue settings interface

  * Option to test your remote queue settings

  * Better support for larger runscripts for queuing systems

* AMSspectra:

  * Support for GW improved

* Preferences:

  * Added region display radius setting

* AMSlevels:

  * DFTB fragment orbitals

* AMSview:

  * Visualization of OLED properties

  * Histograms of atom properties

  * DFTB fragment orbitals

* AMSbands:

  * Support for spin-orbit coupling results

* AMSmovie:

  * Bond source can be chosen. Choices are: auto (prefers stored
    bonds), guessed, initial, or no bonds.

  * PES Exploration/EON energy landscape. Addition of Arrhenius
    prefactors to info and Fragmented states.

  * Acerxn support

  * ChemTraYzer 2:

    * Input

      * setup input (based on json description and .def file

      * AMSinput style unit changes and revert to default (right
        click)

      * when opening the GUI, update the input fields with values as
        found in the chemtrayzer2/job file, if it exists

    * Running

      * run ChemTraYzer 2, job

      * output and results are in chemtrayzer2 folder next to the
        ams.rkf file

      * progress dialog while running, cancel button to interrupt

      * errors from run are reported

    * Output

      * automatically show the results in tables when available

      * right bottom of table: button with name of table, click it to
        open by the OS (on MacOS open the .csv file in Numbers for
        example)

      * tables can be sorted per column

      * tables can be searched, with some advanced search options. use
        help balloon to get info on search syntax

      * feedback on search in status line (number of items found,
        column searched)

      * click, shift-click, control (or right) click to adjust
        selection in tables

      * selection in upper table searches for matching evens in lower
        table

      * selection in lower table shows corresponding atoms (hiding
        other atoms) in corresponding (first) frame in the Movie
        window

      * left-right arrow keys to skip through movie frames

      * up-down arrow keys to move selection up or down (thus go
        through different events for example)

      * escape clears selection, or the search if it has focus

      * if no selection, escape clears the search

  * Mean Square Displacement (MSD) via analysis program

* ParAMS GUI:

  * General

    * 'All', 'Jobs', 'Training Set', 'Validation Set', 'Engines':
      table with training data

    * Molecule window: show system for selected entries

    * 'Info': detailed info for any entry in job collection or
      training data

    * 'Parameters': table with parameters, ranges and other details to
      be optimized

    * 'Params Configuration': show and set up the ParAMS job details

    * 'Graphs': results of optimization in graphs

    * 'Results': text output files

    * import old style reaxff geo/params files

    * revert option to ditch changes due to editing or handling
      results

  * Running

    * run the ParAMS job via AMSjobs

    * opening a ParAMS job will automatically read the results if
      available

    * live update of the results

    * running and live update also work for running on remote machines
      (as all other jobs in AMSjobs)

    * restart a previous run when  using the CMA optimizer

  * Training Data

    * different tabs to show all of these or just one subset (‘All’,
      ‘Jobs’, Training Set’, ‘Validation Set’, ‘Engines’)

    * filter by type of entries (Energies, Bonds, PES, Jobs, Engines,
      …)

    * when multiple systems are relevant for an entry, use arrow left-
      right to move through them

    * add jobs from inside the Params GUI, or via any other GUI module
      (cmd/ctrl - T)

    * use the ParAMS importers to generate training set entries when
      importing a job

    * select atoms to set the proper index when creating some
      expressions

    * menu commands to add most common expressions in the training set

    * edit all (non-output) items in all tables

    * editing via AMSinput for jobs and engines

    * smart editing of multiple items in many cases (expressions for
      multiple items like relative energies, or deactivate all
      selected parameters for example)

    * tab-completion to quickly enter Job IDs

    * energy expressions may be balanced automatically (as they
      correspond to a reaction typically)

    * set up training set and validation set (manual or random)

    * merge training sets / job collections

    * edit all JobIDs at once: prefix or change

    * when results are available the contribution to errors is shown
      with the matching item

    * results are live-updating

  * Parameters

    * ReaxFF, xTB and Lennard-Jones parameters supported

    * detailed information about meaning of parameter and optimization
      range etc

    * adjust parameter optimization range Min and Max

    * generate new ReaxFF blocks, initialize ReaxFF blocks

    * parameters are live-updating

  * ParAMS Configuration

    * set up the params.conf.py file to use for running

    * predefined common options via menus

    * fully editable by user if desired

  * Graphs

    * relevant graphs are shown automatically when running

    * graphs are live-updating

    * validation and training set graphs together, compare with first
      iteration

    * graphs of PES data (like energy vs distance or angle etc)

    * interaction in graphs (click on an item to select matching
      training set entries, and select relevant atoms in molecule
      display if applicable)

    * save graphs as image or xy from File menu

  * Results

    * show text output easily accessible via menus

    * text is live-updating

  * Tables

    * tables can be sorted per column

    * tables can be searched. use help balloon to get info on search
      syntax

    * feedback on search in status line (number of items found, column
      searched)

    * click, shift-click, control (or right) click to adjust selection
      in tables

    * up-down arrow keys to move selection up or down

    * escape clears selection, or the search if it has focus

    * if no selection, escape clears the search

* AMSkinetics

  * Renamed module from Microkinetics

  * Added support for the Kinetic Monte-Carlo program Zacros.
