- 1.7
- 1.6
- 1.5
- Beta
- Examples (for 1.6a)
- Misc
Filter definitions are made in a filter file in a similar way to declaring a user subroutine or function. The 'filter' keyword marks the start of a filter definition, and contains a list of properties in parentheses that define the subsequent filter, its name, and how to recognise the files (from their filenames and/or contents) that it is designed for. The definition of the filter to import XYZ-style model data is as follows:
filter(type="importmodel", name="XMol XYZ Coordinates", nickname="xyz", extension="xyz", glob="*.xyz", id=3)
{
commands
...
}The comma-separated list of properties defines the type of filter ('type="importmodel"') and how to recognise files of that type (e.g., 'extension="xyz"'), amongst other things. The full list of possible properties is as follows:
Table 4.5. Filter properties
| Property | Description |
|---|---|
| exact | Comma-separated list of filenames that are of this type |
| extension | Comma-separated list of filename extensions that indicate files of this type |
| glob | Shell-style glob to use in file fialogs in order to filter out files of the described type |
| id | Numerical ID of the filter to enable partnering of import/export filters for files of the same type |
| name | Descriptive name for the filter, shown in file dialogs etc. |
| nickname | Short name used by commands in order to identify specific filters |
| search | Provides a string to search for in the file. If the string is found, the file is identified as being readable by this filter type. The number of lines searched is governed by the within property |
| type | Defines the kind of filter that is described (i.e. if it loads/saves, acts on models/grid data etc.) so that Aten knows when to use it. Must always be defined! |
| within | Specifies the number of lines to search for any supplied search strings |
| zmap | Determines which zmapping style to employ when converting atom names from the file |
Occasionally (and annoyingly) files have no extension at all, instead having short, fixed names, which must be checked for literally when probing files. This command defines one or more exact filenames that identify files to be acted on by this filter section. Multiple names may be given, separated by commas or whitespace. Exact filename matching is case-insensitive.
For example:
exact="coords"
associates any file called 'coords' to this filter.
exact="results,output"
associates any files called 'results' or 'output' to this filter.
Sets the filename extension(s) that identify files to be read / written by this filter. When files are being probed for their type, in the first instance the filename is examined and the extension (everything after the last '.') is compared to those defined in filter sections by this command. Multiple file extensions may be given, separated by commas or whitespace. File extension matching is case-insensitive.
For example:
extension="xyz"
means that files with extension '.xyz' will be recognised by this filter.
extension="xyz,abc,foo"
means that files with extensions '.xyz', '.abc', and '.foo' will be recognised by this filter.
Sets the file dialog filter extension to use in the GUI, and should be provided as a shell-style glob.
For example:
glob="*.doc"
filters any file matching '*.doc' in the relevant GUI file selector dialogs.
When separate import and export filters for a given file type have been provided it is prudent to associate the pair together so that Aten knows how to save the data that has just been loaded in. Each filter has a user-definable integer ID associated with it that can be used to link import and export filters together. For example, if a model import filter has an ID of 7, and a model export filter also has this ID, then it will be assumed that the two are linked, and that a model saved with export filter 7 can be subsequently loaded with import filter 7. If the ID for a filter is not set it defaults to -1, and it is assumed that no partner exists and the file cannot be directly saved back into this format.
For example:
id =13
![[Note]](images/note.png) | See Also: |
|---|---|
|
Sets the long name of the filter, to be used as the filetype description of files identified by the filter. This name will appear in the file type lists of file dialogs in the GUI, and also in the program output when reading / writing files of the type.
For example:
name="SuperHartree Coordinates File"
Sets a nickname for the filter, which allows it to be identified easily in the command language and, importantly, from the command line. It should be a short name or mnemonic that easily identifies the filter. No checking is made to see if a filter using the supplied nickname already exists.
For example:
nickname="shart"
sets the nickname of the filter to 'shart'.
nickname="zyx"
sets the nickname of the filter to 'zyx'.
Occasionally, checking the contents of the file is the easiest way to determining its type, and is probably of most use for the output of codes where the choice of filename for the results is entirely user-defined. For example, most codes print out a whole load of blurb and references at the very beginning, and usually searching for the program name within this region is enough to identify it. For files that are only easily identifiable from their contents and not their filename, plain text searches within files can be made to attempt to identify them. Individual strings can be given to the 'search' keyword, and multiple 'search' keywords can be provided. The default is to search the first 10 lines of the file for one or more of the defined search strings, but this can be changed with the within property.
For example:
search="UberCode Version 20.0"
matches the filter to any file containing the string 'UberCode Version 20.0' within its first 10 lines (the default).
search="SIESTA"
searches the first 10 lines of the file for the string 'SIESTA'.
search=""GAMESS VERSION = 11 APR 2008 (R1)"
attempts to identify output from a specific version of GAMESS-US.
The 'type' keyword must be provided an all filter definitions - an error will be raised if it is not. It specifies which class of data the filter targets (e.g. models, grid data etc.) and whether it is an import or export filter. A given filter may only have one 'type'. The possible values for 'type' are:
Table 4.6. Filter types
| Type | Description |
|---|---|
| exportexpression | Describes how to export forcefield descriptions (expressions) for models |
| exportgrid | Describes how to export grid-style data |
| exportmodel | Describes how to write out model data |
| exporttrajectory | Filter suitable for the export of trajectory data |
| importexpression | Describes how to load in forcefield-style expressions |
| importgrid | Describes how to read gridded volumetric or surface data from files. Any grids created in these sections must have the finalisegrid command called on them, otherwise they will not be registered properly within the program. |
| importmodel | Describes how to import model data, including atoms, cell and spacegroup data, bonds, glyphs etc. Any models created in 'importmodel' sections must have the finalisemodel command called on them, otherwise they will not be registered properly within the program. |
| importtrajectory | Read frames from trajectory files. See the section on trajectories for additional information on how trajectories are handled within Aten. |
For example:
type="importgrid"
type="exportmodel"
Defines the number of lines to search for any 'search' string definitions (default is 10).
For example:
within=50
specifies that the first 50 lines should be searched for identifying strings.
By default, it is assumed that the commands which create new atoms will be given a proper element symbol from which to determine the atomic number. Case is unimportant, so 'na', 'Na', and 'NA' will all be interpreted as atomic number 11 (sodium). Where element symbols are not used in the model file, there are several alternative options that tell these commands how to convert the element data they are passed into atomic numbers. For example, the 'ff' style is particularly useful when loading in coordinate files which contain forcefield atom type names that do not always correspond trivially to element information (e.g. DL_POLY configurations).
For example:
zmap="numeric"
indicates that atomic numbers are provided in place of element names and no conversion should be performed.
| See Also: |
|---|---|
|