The Interface class provides an interface to external scripts. More...

#include <interfacescript.h>

Inheritance diagram for InterfaceScript:

Public Slots
void	setDebug (bool d)
void	commandFinished ()

Signals
void	finished ()
void	progress (const QString &message, int value, int maximum)

Public Member Functions
	InterfaceScript (const QString &scriptFilePath_, QObject *parent_=nullptr)
	InterfaceScript (QObject *parent_=nullptr)
bool	debug () const
bool	isValid () const
QJsonObject	options () const
QString	displayName () const
QString	menuPath () const
QString	scriptFilePath () const
void	setScriptFilePath (const QString &scriptFile)
void	reset ()
void	setOptionsJson (const QJsonObject &opts)
bool	runCommand (const QJsonObject &options_, Core::Molecule *mol)
void	setCamera (const Matrix4f &modelView, const Matrix4f &projection)
bool	processCommand (Core::Molecule *mol)
bool	generateInput (const QJsonObject &options_, const Core::Molecule &mol)
int	numberOfInputFiles () const
QStringList	fileNames () const
QString	mainFileName () const
QString	fileContents (const QString &fileName) const
QtGui::GenericHighlighter *	createFileHighlighter (const QString &fileName) const
bool	hasErrors () const
void	clearErrors ()
QStringList	errorList () const
QStringList	warningList () const

PythonScript &	interpreter ()
const PythonScript &	interpreter () const

Protected Member Functions
bool	parseJson (const QByteArray &json, QJsonDocument &doc) const
QString	generateCoordinateBlock (const QString &spec, const Core::Molecule &mol) const
void	replaceKeywords (QString &str, const Core::Molecule &mol, const QJsonObject &options) const
QString	generateZMatrixBlock (const QString &spec, const Core::Molecule &mol, bool padded) const
bool	parseHighlightStyles (const QJsonArray &json) const
bool	parseRules (const QJsonArray &json, QtGui::GenericHighlighter &highligher) const
bool	parseFormat (const QJsonObject &json, QTextCharFormat &format) const
bool	parsePattern (const QJsonValue &json, QRegularExpression &pattern) const

Detailed Description

See also: InterfaceWidget

The QuantumInput extension provides a scriptable method for users to add custom input generators to Avogadro. By writing an executable that implements the interface defined below, new input generators can be created faster and easier than writing full Avogadro extensions.

Script Entry Points

The script must handle the following command-line arguments:

--debug Enable extra debugging output. Used with other commands. It is not required that the script support extra debugging, but it should not crash when this option is passed.
--print-options Print the available options supported by the script, e.g. simulation parameters, etc. See below for more details.
--generate-input Read an option block from stdin and print input files to stdout. See below for more details.
--display-name Print a user-friendly name for the input generator. This is used in the GUI for menu entries, window titles, etc.

Specifying parameters with --print-options

The format of the --print-options output must be a JSON object of the following form:

{
  "userOptions": {
    ...
  },
  "highlightStyles": [
    {
      "style": "Descriptive name",
      "rules": [
        {
          "patterns": [ ... ],
          "format": { ... }
        },
        ...
      ],
    },
    ...
  ],
  "inputMoleculeFormat": "cjson"
}

The userOptions block contains a JSON object keyed with option names (e.g. "First option name"), which are used in the GUI to label simulation parameter settings. Various parameter types are supported:

Fixed Mutually-Exclusive Parameter Lists

Parameters that have a fixed number of mutually-exclusive string values will be presented using a QComboBox. Such a parameter can be specified in the userOptions block as:

{
  "userOptions": {
    "Parameter Name": {
      "type": "stringList",
      "values": ["Option 1", "Option 2", "Option 3"],
      "default": 0
    }
  }
}

Here, Parameter Name is the label that will be displayed in the GUI as a label next to the combo box. The array of strings in values will be used as the available entries in the combo box in the order they are written. default is a zero-based index into the values array and indicates which value should be initially selected by default.

Short Free-Form Text Parameters

A short text string can be requested (e.g. for the "title" of an optimization) via:

{
  "userOptions": {
    "Parameter Name": {
      "type": "string",
      "default": "blah blah blah"
    }
  }
}

This will add a QLineEdit to the GUI, initialized with the text specified by default.

Existing files

An input generator can ask for the absolute path to an existing file using the following option block:

{
  "userOptions": {
    "Parameter Name": {
      "type": "filePath",
      "default": "/path/to/some/file"
    }
  }
}

This will add an Avogadro::QtGui::FileBrowseWidget to the GUI, initialized to the file pointed to by default.

Clamped Integer Values

Scripts may request integer values from a specified range by adding a user-option of the following form:

{
  "userOptions": {
    "Parameter Name": {
      "type": "integer",
      "minimum": -5,
      "maximum": 5,
      "default": 0,
      "prefix": "some text ",
      "suffix": " units"
    }
  }
}

This block will result in a QSpinBox, configured as follows:

minimum and maximum indicate the valid range of integers for the parameter.
default is the integer value that will be shown initially.
(optional) prefix and suffix are used to insert text before or after the integer value in the spin box. This is handy for specifying units. Note that any prefix or suffix will be stripped out of the corresponding entry in the call to --generate-input, and just the raw integer value will be sent.

Boolean Parameters

If a simple on/off value is needed, a boolean type option can be requested:

{
  "userOptions": {
    "Parameter Name": {
      "type": "boolean",
      "default": true,
    }
  }
}

This will result in a QCheckBox in the dynamically generated GUI, with the initial check state shown in default.

Special Parameters

Some parameters are common to most calculation codes. If the following parameter names are found, they will be handled specially while creating the GUI. It is recommended to use the names below for these options to provide a consistent interface and ensure that MoleQueue job staging uses correct values where appropriate.

Syntax Highlighting

Rules for syntax highlighting can be specified as a collection of regular expressions or wildcard patterns and text format specifications in the "highlightRules" array. The highlightRules format is:

"highlightStyles": [
  {
    "style": "Style 1",
    "rules": [ (list of highlight rules, see below) ],
  },
  {
    "style": "Style 2",
    "rules": [ (list of highlight rules, see below) ],
  },
  ...
],

The style name is unique to the style object, and used to associate a set of highlighting rules with particular output files. See the --generate-input documentation for more details.

The general form of a highlight rule is:

{
  "patterns": [
    { "regexp": "^Some regexp?$" },
    { "wildcard": "A * wildcard expression" },
    { "string": "An exact string to match.",
      "caseSensitive": false
    },
    ...
  ],
  "format": {
    "preset": "<preset name>"
  }
}

or,

{
  "patterns": [
    ...
  ],
  "format": {
    "foreground": [ 255, 128,  64 ],
    "background": [   0, 128, 128 ],
    "attributes": ["bold", "italic", "underline"],
    "family": "serif"
  }
}

The patterns array contains a collection of fixed strings, wildcard expressions, and regular expressions (using the QRegularExpression syntax flavor, see the QRegularExpression documentation) that are used to identify strings that should be formatted. There must be one of the following members present in each pattern object:

regexp A QRegularExpression-style regular expression. If no capture groups ("(...)") are defined, the entire match is formatted. If one or more capture groups, only the captured texts will be marked.
wildcard A wildcard expression
string An exact string to match.

Any pattern object may also set a boolean caseSensitive member to indicate whether the match should consider character case. If omitted, a case-sensitive match is assumed.

The preferred form of the format member is simply a specification of a preset format. This allows for consistent color schemes across input generators. The recognized presets are:

"title": A human readable title string.
"keyword": directives defined by the target input format specification to have special meaning, such as tags indicating where coordinates are to be found.
"property": A property of the simulation, such as level of theory, basis set, minimization method, etc.
"literal": A numeric literal (i.e. a raw number, such as a coordinate).
"comment": Sections of the input that are ignored by the simulation code.

If advanced formatting is desired, the second form of the format member allows fine-tuning of the font properties:

foreground color as an RGB tuple, ranged 0-255
background color as an RGB tuple, ranged 0-255
attributes array of font attributes, valid strings are "bold", "italic", or "underline"
family of font. Valid values are "serif", "sans", or "mono"

Any of the font property members may be omitted and default QTextCharFormat settings will be substituted.

The input generator extension will apply the entries in the highlightRules object to the text in the order they appear. Thus, later rules will override the formatting of earlier rules should a conflict arise.

Requesting Full Structure of Current Molecule

The inputMoleculeFormat is optional, and can be used to request a representation of the current molecule's geometry when --generate-input is called. The corresponding value indicates the format of the molecule that the script expects. If this value is omitted, no representation of the structure will be provided.

Note: Currently valid options for inputMoleculeFormat are "cjson" for Chemical JSON or "cml" for Chemical Markup Language.

Handling User Selections: --generate-input

When --generate-input is passed, the information needed to generate the input file will be written to the script's standard input channel as JSON string of the following form:

{
  "cjson": {...},
  "options": {
    "First option name": "Value 2",
    "Second option name": "Value 1",
    ...
  }
}

The cjson entry will contain a Chemical JSON representation of the molecule if inputMoleculeFormat is set to "cjson" in the --print-options output. Similarly, a cml entry and CML string will exist if a Chemical Markup Language representation was requested. It will be omitted entirely if inputMoleculeFormat is not set. The options block contains key/value pairs for each of the options specified in the userOptions block of the --print-options output.

If the script is called with --generate-input, it must write a JSON string to standard output with the following format:

{
  "files": [
    {
      "filename": "file1.ext",
      "contents": "...",
      "highlightStyles": [ ... ]
    },
    {
      "filename": "file2.ext",
      "filePath": "/path/to/file/on/local/filesystem"
    },
    ...
  ],
  "warnings": ["First warning.", "Second warning.", ... ],
  "mainFile": "file2.ext"
}

The files block is an array of objects, which define the actual input files. The filename member provides the name of the file, and either contents or filePath provide the text that goes into the file. The contents string will be used as the file contents, and filePath should contain an absolute path to a file on the filesystem to read and use as the input file contents. The optional highlightStyles member is an array of strings describing any highlight styles to apply to the file (see --print-options documentation). Each string in this array must match a style description in a highlighting rule in the --print-options output. Zero or more highlighting styles may be applied to any file. The order of the files in the GUI will match the order of the files in the array, and the first file will be displayed first.

The warnings member provides an array of strings that describe non-fatal warnings to be shown to the users. This is useful for describing the resolution of conflicting options, e.g. "Ignoring basis set for semi-empirical calculation.". This member is optional and should be omitted if no warnings are present.

The mainFile member points to the primary input file for a calculation. This is the file that will be used as a command line argument when executing the simulation code (if applicable), and used by MoleQueue to set the $$inputFileName$$ and $$inputFileBaseName$$ input template keywords. This is optional; if present, the filename must exist in the files array. If absent and only one file is specified in files, the single input file will be used. Otherwise, the main file will be left unspecified.

Automatic Generation of Geometry

The generation of molecular geometry descriptions may be skipped in the script and deferred to the InterfaceScript class by use of a special keyword. The "contents" string may contain a keyword of the form

$$coords:[coordSpec]$$

where [coordSpec] is a sequence of characters. The characters in [coordSpec] indicate the information needed about each atom in the coordinate block. See the CoordinateBlockGenerator documentation for a list of recognized characters.

The geometry may also be written as a z-matrix, with one of

$$zmat:[coordSpec]$$

$$zmatpad:[coordSpec]$$

$$zmat$$ leaves out the fields the opening rows cannot carry, which is what Gaussian, NWChem, Q-Chem, Psi4, Molpro and CFOUR expect; $$zmatpad$$ pads them with zeros instead, which is what ORCA's int format, MOPAC and SIESTA expect. Both take the same [coordSpec] alphabet, extended with I, J and K for the three reference rows and R, A and T for the distance, angle and torsion.

A script that can write either form declares a Coordinates string list option whose values are Cartesian and Z-Matrix / Internal, and puts both keywords in its generated file, each on its own line. Whichever form the user did not choose is removed along with its line, so the script itself needs no branch. A file that offers both forms but comes with no Coordinates option gets the Cartesian block, as it always did.

Only a file offering both forms has anything to choose between: where the surrounding syntax differs too much to write both – ORCA's * gzmt block header, say – the script can branch itself and emit just the one keyword, which is then always used. A file whose only geometry keyword is $$zmat$$ therefore gets a z-matrix whatever the option says, rather than losing its geometry altogether.

Writing a z-matrix may require the atoms to be reordered, since every row has to be measured against atoms already placed. When that happens, or when a linear fragment leaves a row's angle or torsion meaningless, a warning is added to the generated input's warning list.

Other keywords that can be used in the input files are:

$$atomCount$$: Number of atoms in the molecule.
$$bondCount$$: Number of bonds in the molecule.

Progress and Status Updates

A long-running command script can report its progress while it works, so the user sees a determinate progress bar and/or a status message instead of an anonymous spinner. To do so, print a single line of JSON to standard output of the form:

{"avogadro": {"message": "Optimizing conformer 3 of 25", "value": 3, "maximum":

25}}

All three members are optional:

message: status text to display, e.g. "Current energy: -135.2 eV".
value: the current step of a determinate progress bar.
maximum: the total number of steps. Supply value and maximum together; a message on its own just updates the text and leaves the bar as it was.

These lines are consumed by Avogadro and removed from the script's output, so they do not interfere with the final result. A line is only treated as a progress update if it is a complete JSON object on one line with exactly one member, named avogadro, whose value is an object — a pretty-printed result block is never mistaken for one, and any other output the script prints is passed through untouched.

Check AVO_PROGRESS_PROTOCOL before printing an envelope. Avogadro 2.0.0 and earlier read the whole of a script's standard output as a single JSON document, so an extra line makes that parse fail and the command reports an error instead of its result. Avogadro sets this environment variable only when it is reading progress updates, so a script that guards on it keeps working on older releases — it just shows the old indeterminate spinner. The value is the protocol revision, currently 1.

flush=True is required. Python block-buffers standard output when it is connected to a pipe rather than a terminal, so without an explicit flush the updates sit in the buffer and only reach Avogadro when the script exits — by which point the progress bar is gone.

The avogadro.command module (shipped with Avogadro) handles both of these, and is a no-op when progress is unsupported, so it is always safe to call:

from avogadro.command import report_progress
 
for i, conformer in enumerate(conformers, start=1):
    report_progress(f"Conformer {i} of {len(conformers)}", i, len(conformers))
    optimize(conformer)
 
report_progress("Writing results")

That module is not importable in every environment a script may run in (for example a package plugin with its own pixi environment), so scripts are free to copy this self-contained equivalent instead. Do not drop the environment check — without it the script breaks on Avogadro 2.0.0:

import json, os
 
def report_progress(message=None, value=None, maximum=None):
    # Older Avogadro cannot parse these lines; stay silent there.
    if not os.environ.get("AVO_PROGRESS_PROTOCOL"):
        return
    payload = {}
    if message is not None: payload["message"] = message
    if value is not None:   payload["value"] = value
    if maximum is not None: payload["maximum"] = maximum
    # flush=True is required - stdout is block-buffered when piped
    print(json.dumps({"avogadro": payload}), flush=True)

Reporting progress is entirely optional; a script that prints nothing until it is finished behaves exactly as it always has.

The progress dialog shown while a command runs has a Cancel button, which kills the script's process. Scripts that write files or otherwise touch state outside Avogadro should be prepared to be terminated partway through.

Error Handling

In general, these scripts should be written robustly so that they will not fail under normal circumstances. However, if for some reason an error occurs that must be reported to the user, simply write the error message to standard output as plain text (i.e. not JSON), and it will be shown to the user.

While a command script runs (--run-command), its standard output and standard error are kept separate: the result and any plain-text error belong on standard output, while standard error is captured for diagnostics and reported if the output cannot be parsed. This means library chatter and warnings on standard error cannot corrupt the result.

Debugging

Debugging may be enabled by defining AVO_QM_INPUT_DEBUG in the process's environment. This will cause the –debug option to be passed in all calls to generator scripts, and will print extra information to the qDebug() stream from within avogadro. The script is free to handle the debug flag as the author wishes.

Constructor & Destructor Documentation

◆ InterfaceScript()

InterfaceScript	(	const QString &	scriptFilePath_,
		QObject *	parent_ = nullptr )

explicit

Constructor

Parameters

scriptFilePath_ Absolute path to generator script.

Member Function Documentation

◆ debug()

bool debug ( ) const

Returns: True if debugging is enabled.

◆ isValid()

bool isValid ( ) const

Returns: True if the generator is configured with a valid script.

◆ options()

QJsonObject options ( ) const

Query the script for the available options (–generate-options) and return the output as a JSON object.

Note: The results will be cached the first time this function is called and reused in subsequent calls.; If an error occurs, the error string will be set. Call hasErrors() to check for success, and errorString() or errorList() to get a user-friendly description of the error.

◆ displayName()

QString displayName ( ) const

Return a user-friendly name for the script.

Note: In package mode this is taken from package metadata. For legacy script mode, the value is queried from –display-name.; The results will be cached the first time this function is called and reused in subsequent calls.; If an error occurs, the error string will be set. Call hasErrors() to check for success, and errorString() or errorList() to get a user-friendly description of the error.

◆ menuPath()

QString menuPath ( ) const

Query the script for the menu path (–menu-path).

Note: The results will be cached the first time this function is called and reused in subsequent calls.; If an error occurs, the error string will be set. Call hasErrors() to check for success, and errorString() or errorList() to get a user-friendly description of the error.

◆ scriptFilePath()

QString scriptFilePath ( ) const

Returns: The path to the generator file.

◆ setScriptFilePath()

void setScriptFilePath ( const QString & scriptFile )

Set the path to the input generator script file. This will reset any cached data held by this class.

◆ interpreter() [1/2]

PythonScript & interpreter ( )

Access to the underlying PythonScript interpreter for direct configuration (e.g. setting package mode via setPackageInfo()).

◆ interpreter() [2/2]

const PythonScript & interpreter ( ) const

Access to the underlying PythonScript interpreter for direct configuration (e.g. setting package mode via setPackageInfo()).

◆ reset()

void reset ( )

Clear any cached data and return to an uninitialized state.

◆ setOptionsJson()

void setOptionsJson ( const QJsonObject & opts )

Set the user options directly from a JSON object, bypassing the –print-options script call. Use this for package-based plugins whose options are stored in a file referenced by the pyproject.toml metadata. Insert "inputMoleculeFormat" into opts before calling if you need a specific molecule format (mirrors the InputGenerator::setOptions() pattern). After calling this, reloadOptions() on the widget will use the cached options without invoking the script.

◆ runCommand()

bool runCommand	(	const QJsonObject &	options_,
		Core::Molecule *	mol )

Asynchronously run a command script using the supplied options object and molecule. See the class documentation for details on the options_ object format.

Returns: true on success and false on failure.

Note: If an error occurs, the error string will be set. Call hasErrors() to check for success, and errorString() or errorList() to get a user-friendly description of the error.

◆ setCamera()

void setCamera	(	const Matrix4f &	modelView,
		const Matrix4f &	projection )

Supply the current view camera, so that the CJSON handed to the script carries the orientation the user is actually looking at.

The matrices are written to the CJSON as properties.modelView and properties.projection, the same keys CjsonFormat uses, and they override any stale matrices the molecule kept from the file it was read from. Without this, a script only ever sees the camera as of the last save.

Parameters

modelView	The camera's world-to-eye transform.
projection	The camera's projection matrix. Its (3, 3) element is 0 for a perspective camera and 1 for an orthographic one.

◆ processCommand()

bool processCommand ( Core::Molecule * mol )

Finish processing an asynchronous command script

◆ generateInput()

bool generateInput	(	const QJsonObject &	options_,
		const Core::Molecule &	mol )

Request input files from the script using the supplied options object and molecule. See the class documentation for details on the options_ object format.

If the files are generated successfully, use the functions numberOfInputFiles(), fileNames(), and fileContents() to retrieve them.

Returns: true on success and false on failure.

Note: If an error occurs, the error string will be set. Call hasErrors() to check for success, and errorString() or errorList() to get a user-friendly description of the error.

◆ numberOfInputFiles()

int numberOfInputFiles ( ) const

Returns: The number of input files stored by generateInput().

Note: This function is only valid after a successful call to generateInput().

◆ fileNames()

QStringList fileNames ( ) const

Returns: A list of filenames created by generateInput().

Note: This function is only valid after a successful call to generateInput().

◆ mainFileName()

QString mainFileName ( ) const

Returns: The "main" input file of the collection. This is the input file used by MoleQueue to determine the $$inputFileName$$ and $$inputFileBaseName$$ keywords.

Note: This function is only valid after a successful call to generateInput().

◆ fileContents()

QString fileContents ( const QString & fileName ) const

Returns: A file contents corresponding to fileName. Must call generateInput() first.

See also: fileNames

◆ createFileHighlighter()

QtGui::GenericHighlighter * createFileHighlighter ( const QString & fileName ) const

Returns: A syntax highlighter for the file fileName. Must call generateInput() first. The caller takes ownership of the returned object. If no syntax highlighter is defined, this function returns nullptr.

See also: fileNames

◆ hasErrors()

bool hasErrors ( ) const

Returns: True if an error is set.

◆ clearErrors()

void clearErrors ( )

Reset the error counter.

◆ errorList()

QStringList errorList ( ) const

Returns: A QStringList containing all errors that occurred in the last call to the input generator script.

◆ warningList()

QStringList warningList ( ) const

Returns: A QStringList containing all warnings returned by the input generator script in the last call to generateInput. These are script-specific warnings.

◆ progress

void progress	(	const QString &	message,
		int	value,
		int	maximum )

signal

A running command script reported its progress. See the "Progress and Status Updates" section above for the script-side protocol.

Parameters

message	Status text to show, or an empty string if the script did not supply one.
value	The current step, or -1 if the script did not supply one.
maximum	The total number of steps, or -1 if the script did not supply one.

◆ setDebug

void setDebug ( bool d )

slot

Enable/disable debugging.

◆ commandFinished

void commandFinished ( )

slot

Receives a signal when asynchronous command scripts are finished

The documentation for this class was generated from the following file:

interfacescript.h

Public Slots

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Script Entry Points

Specifying parameters with --print-options

Fixed Mutually-Exclusive Parameter Lists

Short Free-Form Text Parameters

Existing files

Clamped Integer Values

Boolean Parameters

Special Parameters

Syntax Highlighting

Requesting Full Structure of Current Molecule

Handling User Selections: --generate-input

Automatic Generation of Geometry

Progress and Status Updates

Error Handling

Debugging

Constructor & Destructor Documentation

◆ InterfaceScript()

Member Function Documentation

◆ debug()

◆ isValid()

◆ options()

◆ displayName()

◆ menuPath()

◆ scriptFilePath()

◆ setScriptFilePath()

◆ interpreter() [1/2]

◆ interpreter() [2/2]

◆ reset()

◆ setOptionsJson()

◆ runCommand()

◆ setCamera()

◆ processCommand()

◆ generateInput()

◆ numberOfInputFiles()

◆ fileNames()

◆ mainFileName()

◆ fileContents()

◆ createFileHighlighter()

◆ hasErrors()

◆ clearErrors()

◆ errorList()

◆ warningList()

◆ progress

◆ setDebug

◆ commandFinished