Input Contexts

On this page you will find information about

When evaluating an expression, the Evaluator substitutes data reference symbols by the corresponding data items.

Data groups

All data items belong to exactly one of the following data groups:

  1. constants
    data having the same value at each evaluation

    • numerical or string constants (e.g. 5, 7.4, "acidic", "mols/amine.mol", "NCC(N)C1=CC(=CC=C1)C(O)=O")

    • molecule constants declared in the configuration XML (e.g. nitro, hydrazide, carboxyl)

  2. inputs
    data possibly changing for each evaluation, such as

    • input molecules and atoms,

    • input reactants for reaction processing,

    • created products in reaction processing

Expression evaluation environments

The type of the input data depends on the expression evaluation environment, which currently is one of the following:

  1. an expression string evaluated by the command line version of Evaluator refers to the current input molecule read from the input file(s) or the standard input

  2. an inner atomic expression refers to both the input molecule and the current atom - it is used when a Chemical Terms expression is evaluated on some or all atoms of the input molecule (e.g. atom filtering conditions, atomic evaluators and min-max evaluators)

  3. a reaction condition can refer to a reactant and a product array as well as to their atoms mapped according to the reaction equation

Input contexts

The evaluation environment provides a specific input context for accessing its input data. The input context consists of a bunch of accessor functions that can be used in the expression strings to access the input data.

The following input contexts correspond to the evaluation environments described above:

  1. molecule context, used for single molecule input (e.g. command line Evaluator, Chemical Terms - JChem Cartridge):

    • mol(): refers to the current input molecule

  2. atom context, used for single atom input (e.g. inner atomic expressions):

    • mol(): refers to the current input molecule

    • atom(): refers to the current input atom index in the input molecule

  3. search context, used for filtering search hits (e.g. jcsearch and search queries):

    • mol(), target(): both refer to the search target molecule

    • query(): refers to the search query molecule

    • m(int i): refers to the query atom index with atom map i

    • hit(), h(): both refer to the search hit array

    • hit(int i), h(int i): both refer to the i-th element of the search hit array, this is the target atom index matching the query atom with atom index i

    • hm(int i): refers to the target atom index matching the query atom with atom map i (shorthand for h(m(i)))

  4. reaction context, used for reaction input initiated by the Chemical Terms - Reactor:

    • reactant(int i): refers to the i-th reactant (0-based indexing)

    • product(int i): refers to the i-th product (0-based indexing)

    • ratom(int m): refers to the reactant atom corresponding to reactant atom map m according to the reaction equation

    • patom(int m): refers to the product atom corresponding to product atom map m according to the reaction equation

    In reaction context atoms also can be referred by atom index, but in this case the molecule (reactant / product) parameter always have to be specified in the parameter list of the function (see this example).

Note that the default input molecule is the molecule returned by mol() in case this function exists in the context.