Presets and Defaults
********************

AMSinput presets define input values to be used for some input
options, replacing the normal default values.

A preset normally sets just a few input options. After you have
selected a preset, fields that are set by the selected preset will be
shown with a green color.

Fields that are adjusted by the user will **NOT** be overwritten when
using a preset, they will be marked with a red color if the preset has
a different value.

A special preset **None** is included which sets no options. Using it
will revert all fields that are not adjusted by the user (all green
fields) to their default values.

Note:

  If you used SinglePoint.tpl to define defaults for everything,
  rename that file to *_*.tpl. SinglePoint is no longer a special task
  name for preset matching; use the * wildcard for task and/or module.


When are presets used
=====================

AMSinput sets defaults (for all fields) according to the SCM Defaults
preset and the user Defaults preset (if present) on startup. Next,
other presets may be loaded:

1. Automatic preset loading

AMSinput tries to load a matching preset when the user switches module
(ADF, BAND, etc.) or task. First the matching preset is determined. If
it is different from the current preset in use (if any), it will be
used. If no matching preset is found, and the current preset no longer
matches the current module/task, the **None** preset is used.

2. User loading a preset

A preset is also used when explicitly selected by the user from the
File -> Preset menu. Alternatively, right-click on a field to get a
pop-up menu with options to reset that particular field, or to save a
particular preset.

3. User resetting preset values

Use the Reset option (Reset To AMS_Defaults for example) in the Preset
menu to reset all values to the defaults, without applying any other
preset. The **None** preset is similar, it resets all fields set by
the current preset but leaves fields changed by the user as they are.


Saving presets
==============

You can save a preset using the File -> Preset -> Save... menu
command.

Note:

  Many input options are shared between modules, like most AMS driver
  options. Adjusting them for one module will also adjust them for
  other modules.

If you make your preset module specific (for example by saving it with
name ADF) it will only be used for that module. Switching to another
module will reset to **None** (or some other matching preset).

In the help balloon you can find detailed information about the
matching rules for presets, which determine the preset automatically
used.

By default presets are saved in the $HOME/.scm_gui/Tpl directory. This
can be changed by setting the SCM_TPLDIR environment variable.

Preset names must be plain names (no path components). The characters
"/", "\" and ".." are not allowed. You may include a ".tpl" extension
when saving; AMSinput removes it automatically and still writes a
".tpl" file.

If you save a preset with the same name as one of the default presets,
it will effectively replace that preset. One exception: the SCM
supplied Defaults are always read first, and thus cannot be replaced.

To delete your own preset(s), use the 'Delete' command from the Preset
menu.


Matching presets with modules / tasks
=====================================

When you switch the Task or Module, AMSinput will try to load a
matching preset.

When a preset switch happens, values from the current preset are first
reverted to defaults for fields that were not user-changed. Next the
first matching preset will be loaded according to these matches (top
to bottom):


Matching precedence (highest first)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+----------------------+------------------------------------------+------------------------------------------+
| Pattern              | Meaning                                  | Example file name                        |
|======================|==========================================|==========================================|
| "Module_Task"        | Module and task must match               | "ADF_SinglePoint.tpl"                    |
+----------------------+------------------------------------------+------------------------------------------+
| "Module_*"           | Module must match, any task              | "DFTB_*.tpl"                             |
+----------------------+------------------------------------------+------------------------------------------+
| "Module" (no         | Module must match, any task              | "BAND.tpl"                               |
| underscore)          |                                          |                                          |
+----------------------+------------------------------------------+------------------------------------------+
| "*_Task"             | Task must match, any module              | "*_GeometryOptimization.tpl"             |
+----------------------+------------------------------------------+------------------------------------------+
| "*_*"                | Always matches                           | "*_*.tpl"                                |
+----------------------+------------------------------------------+------------------------------------------+

For presets to match, spaces and minus signs are ignored. The Module
names should be as visible in AMSinput (in the orange menu). For
example, "Force Field_*" and "ForceField_*" match the same module, and
"Quantum ESPRESSO_*" and "QuantumESPRESSO_*" also match the same
module.


Why a preset may not apply
==========================

If a preset does not seem to apply, check the following:

* The module/task name in the file name does not match the current
  module/task (after ignoring spaces and "-").

* Another preset with higher precedence matches first.

* You changed the field manually after the preset was loaded. User-
  changed fields are not overwritten by later preset loads.

* No preset matches the current module/task. In that case AMSinput
  falls back to **None** (reverting non-user-changed preset values to
  defaults).


Default values used
===================

AMSinput always first uses the Defaults preset as included by SCM.

Next the Defaults preset defined by the user (if any).

Next default values defined in the code (via the input_def json files)
will be used, but only if they have not yet been set.

Next a preset matching the current module and task will be loaded
(either from SCM or defined by the user). Fields that are adjusted by
the user will **NOT** be overwritten when using a preset, they will be
marked with a red color if the preset has a different value.

Finally, a user may force a preset to be used via the File -> Preset
menu. This overrides the automatically loaded preset from the previous
step. Again, fields that are adjusted by the user will **NOT** be
overwritten when using a preset, and they will be marked red if the
preset has a different value.


Color Code
==========

The input fields use a color coding to warn you they have been
modified:

* No special color: the field has its default value (from Defaults.tpl
  by SCM or by the user).

* Yellow: the field has been changed by the user (only).

* Green: the field has been changed by the preset (only).

* Red: the field has been changed by the preset, and next by the user.

The pull-down menus in the panel bar use a similar color-coding to
point you to fields that have been changed:

* No special color: all fields in the panel have their original
  default value.

* Yellow: some fields have been changed by the user.

* Green: some fields have been changed by the preset.

* Red: some fields have been changed by the preset, and some (possibly
  also) by the user.


Input options remarks
=====================


Spin and Occupation
-------------------

The spin and occupation panel allows you to specify the occupations of
the orbitals per symmetry. In case of an unrestricted calculation you
can also specify the occupations per spin type.

To show the available symmetries, AMSinput needs the result of an ADF
calculation. If a previous calculation is available (without
specifying the occupations), it will use the information from that
calculation to generate the proper options in this panel. If such
results are not available, AMSinput will suggest to run a short guess
calculation: a preliminary run with an inaccurate grid, only a few SCF
cycles and stopping immediately after the SCF. Hopefully this guess
calculation will allow you to generate sensible occupation.

The energy levels of the guess calculation (or previous calculation if
available) will be shown using AMSlevels. Be aware that it is the
result of the guess calculation, and not your proper results!
