CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [0.5.5] - 2025-01-13
+
+### Added
+- **docs**: add FAQ to docs ([#392](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/392))
+- **docs**: add a link in the docs regarding FireWorks setup ([#387](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/387))
+- **amml**: implement velocity distributions ([#385](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/385))
+- **interpreter**: add support for tuple subscripting ([#379](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/379))
+- **amml**: enable plotting reaction energy profile diagrams ([#371](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/371))
+
+### Fixed
+- **interpreter**: infer the subdtype but not convert to default subdtype with pint-pandas >=0.7 ([#396](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/396), [#398](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/398))
+- **interpreter**: add end-of-file to terminated general reference rule to allow variable with a single reference as parameter ([#389](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/389))
+- **interpreter**: fix diverse type errors causing crashes ([#394](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/394))
+- **interpreter**: prevent crash when printing function value in asynchronous on-demand evaluation ([#391](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/391))
+- **grammar**: prevent crash with numeric literal in place of units ([#388](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/388))
+- **interpreter**: handle exceptions from database with large documents (solved in the context of [#388]((https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/388)))
+- **cli**: prevent crash in the import section of text session ([#384](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/384))
+- **constraints**: check first argument of issubclass ([#382](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/382))
+- **interpreter**: prevent crash with type() function applied to imports ([#386](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/386))
+- **examples**: update the examples for the recent grammar changes ([#380](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/380))
+- **interpreter**: prevent evaluating non-active models in case of synchronous and asynchronous on-demand workflow evaluation ([#381](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/381))
+- **docs**: correct the docs section about extending SCL ([#378](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/378))
+
+### Changed
+- **cli**: revise some CLI options: remove `--textx-debug`, add `%help` in `%help` menu; produce warnings for ignored parameters ([#397](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/397))
+- **docs**: adjust the docs for how to use the wfengine file dumped by `texts session` ([#397](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/397))
+- **amml**: adapt calculator parameters due to task ([#274](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/274))
+- **grammar**: remove variable tuple from grammar, interpreter, examples, tests, and docs ([#379](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/379))
+- **cli**: sort model history by time stamps ([#368](https://gitlab.kit.edu/kit/virtmat-tools/vre-language/-/issues/368))
+
 
 ## [0.5.4] - 2024-11-28
 ### Added

docs/amml.md

@@ -111,7 +111,7 @@ Calculator <name> [ >|<|==|>=|<= <version>] ()[, task: <task>]
 
 The specification of `name` is mandatory. Currently `name` must be one of `vasp`, `turbomole`, `lj`, `emt`, `free_electrons`.
 
-The version specification is optional. Currently it is not interpreted.
+The version specification is optional. The version must be [semantic version](https://semver.org) and is interpreted in calculators for [codes are not part of ASE](https://wiki.fysik.dtu.dk/ase/ase/calculators/calculators.html#supported-calculators), such as VASP and Turbomole.
 
 The actual calculator parameters can be specified as series in the top-level table. The paramater names, type and units depend on the calculator. The table below lists the parameters of the currently supported calculators. If only default parameters have to be used then no `Table` parameter is needed and the syntax is `(default)` or simply `()`.
 
@@ -517,10 +517,10 @@ The [`view` statement](scl.md#the-view-statement) can be used to visualize and a
 
 ### Visualize / analyze atomic structures
 
-Parameters of type [AMML Structure](amml.md#structure) can be viewed using this simple syntax:
+Parameters of type [AMML Structure](amml.md#structure) with optional geometry constraints can be viewed using this syntax:
 
 ```
-view structure (struct)
+view structure (struct, [(constr1, [[constr2], ...])])
 ```
 
 ### Visualize a trajectory

setup.cfg

 [metadata]
 name = vre-language
-version = 0.5.4
+version = 0.5.5
 author = The Virtmat Tools Team
 author_email = virtmat-tools@lists.kit.edu
 description = VRE Language
@@ -38,7 +38,7 @@ install_requires =
     numpy
     pandas >=2.2.0
     pint >=0.24.3
-    pint-pandas ==0.6.2
+    pint-pandas ==0.7.1
     fireworks >=2.0.3
     pyyaml
     dill

src/virtmat/language/cli/run_model.py

@@ -9,10 +9,11 @@ from fireworks.user_objects.queue_adapters.common_adapter import CommonAdapter
 from virtmat.language.metamodel.properties import add_properties
 from virtmat.language.metamodel.processors import add_processors
 from virtmat.language.interpreter.session import Session
+from virtmat.language.utilities.textx import GRAMMAR_LOC, GrammarString
+from virtmat.language.utilities.compatibility import check_compatibility
 from virtmat.language.utilities.errors import error_handler, ConfigurationError
 from virtmat.language.utilities.warnings import warnings, TextSUserWarning
 from virtmat.language.utilities.fireworks import object_from_file
-from virtmat.language.utilities.textx import GRAMMAR_LOC
 from virtmat.language.utilities.ioops import get_datastore_config, GRIDFS_DATASTORE
 from virtmat.language.utilities import logging
 
@@ -73,6 +74,7 @@ def run_instant_deferred(clargs, deferred=False, apply_constraints=True):
     for attr, val in attrs.items():
         check_clargs(attr, val, bstr)
 
+    check_compatibility(GrammarString(clargs.grammar_path).string)
     meta = metamodel_from_file(clargs.grammar_path, auto_init_attributes=False)
     add_properties(meta, deferred_mode=deferred)
     add_processors(meta, constr_processors=apply_constraints)

src/virtmat/language/constraints/amml.py

 """checks / constraints for AMML objects"""
 from textx import get_children_of_type
+from virtmat.language.utilities.errors import StaticTypeError
 from virtmat.language.utilities.errors import raise_exception, StaticValueError
 from virtmat.language.utilities.textx import get_reference
+from virtmat.language.utilities.typemap import typemap
 from virtmat.language.utilities.ase_params import spec
 
 task_properties = {
@@ -44,3 +46,28 @@ def check_amml_property_processor(model, _):
             if not algo and calc_task and name not in task_properties[calc_task]:
                 msg = f'property \"{name}\" not available in task \"{calc_task}\"'
                 raise_exception(obj, StaticValueError, msg)
+
+
+def check_view_amml_structure_processor(model, _):
+    """check the parameters of view structure statements"""
+    for obj in get_children_of_type('View', model):
+        if obj.mode != 'structure':
+            continue
+        if len(obj.params) > 2:
+            msg = f'view structure has maximum 2 parameters but {len(obj.params)} given'
+            raise_exception(obj, StaticTypeError, msg)
+        if obj.params[0].type_:
+            if not issubclass(obj.params[0].type_, typemap['AMMLStructure']):
+                msg = (f'parameter must be type {typemap["AMMLStructure"].__name__}'
+                       f' but is type {obj.params[0].type_.__name__}')
+                raise_exception(obj.params[0], StaticTypeError, msg)
+        if len(obj.params) == 2:
+            if obj.params[1].type_:
+                if not issubclass(obj.params[1].type_, typemap['Tuple']):
+                    msg = 'parameter must be Tuple of constraints'
+                    raise_exception(obj.params[1], StaticTypeError, msg)
+                for type_ in obj.params[1].type_.datatype:
+                    if type_ and not issubclass(type_, typemap['AMMLConstraint']):
+                        msg = (f'parameter must be type {typemap["AMMLConstraint"].__name__}'
+                               f' but is type {type_.__name__}')
+                        raise_exception(obj.params[1], StaticTypeError, msg)

src/virtmat/language/constraints/processors.py

@@ -20,6 +20,7 @@ from .functions import check_functions_processor
 from .imports import check_imports_processor
 from .units import check_units_processor
 from .parallel import check_parallelizable_processor
+from .view import check_view_processor
 from .amml import check_amml_property_processor
 from .chem import check_chem_reaction_processor
 
@@ -122,5 +123,6 @@ def add_constraints_processors(metamodel):
     metamodel.register_model_processor(check_parallelizable_processor)
     metamodel.register_model_processor(check_vary_processor)
     metamodel.register_model_processor(check_tag_processor)
+    metamodel.register_model_processor(check_view_processor)
     metamodel.register_model_processor(check_amml_property_processor)
     metamodel.register_model_processor(check_chem_reaction_processor)

src/virtmat/language/constraints/view.py

+"""apply constraints for all view statements"""
+from virtmat.language.utilities.errors import textxerror_wrap
+from .amml import check_view_amml_structure_processor
+
+
+@textxerror_wrap
+def check_view_processor(model, metamodel):
+    """apply constraints for all view statements"""
+    # check_view_lineplot_processor(model, metamodel)
+    # check_view_scatterplot_processor(model, metamodel)
+    check_view_amml_structure_processor(model, metamodel)
+    # check_view_amml_trajectory_processor(model, metamodel)
+    # check_view_amml_vibration_processor(model, metamodel)
+    # check_view_amml_neb_processor(model, metamodel)
+    # check_view_amml_bs_processor(model, metamodel)
+    # check_view_amml_eos_processor(model, metamodel)
+    # check_view_amml_waterfall_processor(model, metamodel)

src/virtmat/language/grammar/identifiers.tx

@@ -61,9 +61,3 @@ SeriesID:
 Dummy:
   name = TrueID &/,|\)|\:/
 ;
-
-// semantic versioning
-
-SemVer:
-  INT('.' INT)*
-;

src/virtmat/language/grammar/semversion.tx

+/* semantic versioning https://semver.org */
+
+// parsing using a regex is somewhat slower than using textx grammar
+
+/*
+SemVer:
+  /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?/
+;
+*/
+
+/* https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions */
+
+SemVer:
+  SemVerCore ( '-' SemVerPreRelease )? ( '+' SemVerBuild )?
+;
+
+SemVerCore:
+  SemVerNumericID '.' SemVerNumericID '.' SemVerNumericID
+;
+
+SemVerPreRelease:
+  SemVerPreReleaseID+['.']
+;
+
+SemVerPreReleaseID:
+  SemVerAlphaNumericID | SemVerNumericID
+;
+
+SemVerBuild:
+  SemVerBuildID+['.']
+;
+
+SemVerBuildID:
+  SemVerAlphaNumericID | SemVerDigit+
+;
+
+SemVerAlphaNumericID:
+  ( SemVerNonDigit | ( SemVerIDCharacter+ SemVerNonDigit ) ) SemVerIDCharacter*
+;
+
+SemVerNumericID:
+  SemVerDigit+
+;
+
+SemVerIDCharacter:
+  SemVerDigit | SemVerNonDigit
+;
+
+SemVerNonDigit:
+  SemVerLetter | '-'
+;
+
+SemVerLetter:
+  /[a-zA-Z]/
+;
+
+SemVerDigit:
+  /[0-9]/
+;

src/virtmat/language/grammar/virtmat.tx

 /* grammar for virtmat modeling language */
-/* grammar version 29 */
+/* grammar version 30 */
 
 import imports
 import identifiers
 import types
 import resources
 import arrays
+import semversion
 
 
 Program[noskipws]:

src/virtmat/language/interpreter/deferred_executor.py

@@ -32,10 +32,13 @@ from virtmat.language.utilities.types import is_scalar_type, is_numeric_type
 from virtmat.language.utilities.types import get_datatype_name
 from virtmat.language.utilities.lists import get_array_aslist
 from virtmat.language.utilities.units import get_units, get_dimensionality
+from virtmat.language.utilities.units import convert_series_units
 from virtmat.language.utilities.arrays import get_nested_array
 from virtmat.language.utilities import amml, chemistry
 from .instant_executor import program_value, plain_type_value
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 # binary operator--function map
 binop_map = {'>': gt, '<': lt, '==': eq, '!=': ne, '<=': le, '>=': ge,
              '+': add, '-': lambda x, y: add(x, neg(y)), '*': mul, '/': truediv,
@@ -86,7 +89,7 @@ def print_parameter_func(self):
             return val.to(units)
         assert isinstance(val, typemap['Series'])
         if isinstance(val.dtype, pint_pandas.PintType):
-            return val.pint.to(units)
+            return convert_series_units(val, units)
         assert val.dtype == 'object'
         elems = [elem.to(units) for elem in val]
         return typemap['Series'](name=val.name, data=elems, dtype='object')

src/virtmat/language/interpreter/instant_executor.py

@@ -26,10 +26,13 @@ from virtmat.language.utilities.types import is_scalar_type, is_scalar, settype
 from virtmat.language.utilities.types import get_datatype_name
 from virtmat.language.utilities.lists import get_array_aslist
 from virtmat.language.utilities.units import get_units, get_dimensionality
+from virtmat.language.utilities.units import convert_series_units
 from virtmat.language.utilities.ioops import load_value
 from virtmat.language.utilities.arrays import get_nested_array
 from virtmat.language.utilities import amml, chemistry
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 comp_operators = ('>', '<', '==', '!=', '<=', '>=')
 comp_functions = (gt, lt, eq, ne, le, ge)
 comp_map = dict(zip(comp_operators, comp_functions))
@@ -137,7 +140,7 @@ def print_parameter_value(self):
         return value.to(self.inp_units)
     assert isinstance(value, typemap['Series'])
     if isinstance(value.dtype, pint_pandas.PintType):
-        return value.pint.to(self.inp_units)
+        return convert_series_units(value, self.inp_units)
     assert value.dtype == 'object'
     elems = [e.to(self.inp_units) for e in value]
     return typemap['Series'](name=value.name, data=elems, dtype='object')

src/virtmat/language/interpreter/session.py

@@ -16,7 +16,6 @@ from virtmat.language.utilities.errors import ModelNotFoundError, ConfigurationE
 from virtmat.language.utilities.errors import VaryError, ReuseError
 from virtmat.language.utilities.warnings import warnings, TextSUserWarning
 from virtmat.language.utilities.compatibility import check_compatibility
-from virtmat.language.utilities.compatibility import CompatibilityError, versions
 from virtmat.language.utilities.logging import get_logger
 from virtmat.language.utilities.formatters import formatter
 from virtmat.language.utilities.fireworks import get_nodes_info, get_nodes_providing
@@ -105,8 +104,8 @@ class Session:
             self.uuids = [wfl['metadata']['uuid'] for wfl in wflows]
             assert uuid in self.uuids
             for wfl in wflows:
-                check_compatibility(wfl['metadata']['grammar_str'],
-                                    match['metadata'].get('data_schema_version', None))
+                schema_ver = match['metadata'].get('data_schema_version', None)
+                check_compatibility(wfl['metadata']['grammar_str'], data_schema=schema_ver)
             self.models = [None]*len(self.uuids)
             self.logger.debug('loaded group with uuid %s', self.g_uuid)
             self.logger.debug('loaded group of models with uuids %s', self.uuids)
@@ -302,16 +301,9 @@ class Session:
                     'spec._grammar_version': True, 'spec._data_schema_version': True}
             wfl = get_nodes_info(self.lpad, wf_q, fw_q, proj)[0]
             for node in wfl['nodes']:
-                version = node['spec'].get('_grammar_version')
-                if version not in versions['grammar']:
-                    msg = (f"Source-model grammar has version {version} but the "
-                           f"supported versions are {versions['grammar']}")
-                    raise CompatibilityError(msg)
-                version = node['spec'].get('_data_schema_version')
-                if version not in versions['data_schema']:
-                    msg = (f"Source-model data schema has version {version} but the "
-                           f"supported versions are {versions['data_schema']}")
-                    raise CompatibilityError(msg)
+                grammar_ver = node['spec'].get('_grammar_version')
+                schema_ver = node['spec'].get('_data_schema_version')
+                check_compatibility(grammar_ver=grammar_ver, data_schema=schema_ver)
             vars_ = [v for n in wfl['nodes'] for t in n['spec']['_tasks'] for v in t['outputs']]
             if not src_var_names.isdisjoint(vars_):
                 confl = src_var_names.intersection(vars_)

src/virtmat/language/utilities/amml.py

@@ -29,6 +29,8 @@ from virtmat.language.utilities.units import ureg, get_pint_series
 from virtmat.language.utilities.lists import list_flatten
 from virtmat.language.utilities.formatters import formatter
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 
 def get_structure_dataframe(atoms):
     """create a structure dataframe from an ASE Atoms object"""

src/virtmat/language/utilities/ase_handlers.py

@@ -10,6 +10,8 @@ from virtmat.language.utilities.errors import PropertyError
 from virtmat.language.utilities.units import ureg
 from . import amml
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 EC_ANG = 'elementary_charge * angstrom'
 EC_BOHR = 'elementary_charge * bohr'
 EV_PER_ANG = 'eV / angstrom'

src/virtmat/language/utilities/ase_viewers.py

@@ -24,7 +24,12 @@ def show_atoms(atoms, show=True):
 
 def display_amml_structure(obj, show=True):
     """display an atomic structure using ASE"""
-    show_atoms(obj.params[0].value.to_ase(), show=show)
+    atoms_lst = obj.params[0].value.to_ase()
+    if len(obj.params) == 2:
+        constraints = [c for cs in obj.params[1].value for c in cs.to_ase()]
+        for atoms_obj in atoms_lst:
+            atoms_obj.constraints = constraints
+    show_atoms(atoms_lst, show=show)
 
 
 def display_amml_trajectory(obj, show=True):

src/virtmat/language/utilities/chemistry.py

@@ -8,6 +8,8 @@ from virtmat.language.utilities.units import ureg
 from virtmat.language.utilities.errors import RuntimeValueError
 from virtmat.language.utilities.warnings import warnings, TextSUserWarning
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 
 def is_equation_balanced(lcomps, lcoeff, rcomps, rcoeff):
     """check equation balance using provided a list of compositions and coefficients"""

src/virtmat/language/utilities/compatibility.py

@@ -3,7 +3,7 @@ import re
 from virtmat.language.utilities.logging import get_logger
 
 versions = {'grammar': [14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 25, 26, 27, 28,
-                        29],
+                        29, 30],
             'data_schema': [6, 7]}
 
 
@@ -22,12 +22,14 @@ def get_grammar_version(grammar_str):
     return version
 
 
-def check_compatibility(grammar_str, data_schema=None):
+def check_compatibility(grammar_str=None, grammar_ver=None, data_schema=None):
     """check compatibility of grammar and data schema"""
     logger = get_logger(__name__)
-    version = get_grammar_version(grammar_str)
-    if version not in versions['grammar']:
-        msg = (f"Provided grammar has version {version} but the supported "
+    assert grammar_str is not None or grammar_ver is not None
+    if grammar_ver is None:
+        grammar_ver = get_grammar_version(grammar_str)
+    if grammar_ver not in versions['grammar']:
+        msg = (f"Provided grammar has version {grammar_ver} but the supported "
                f"versions are {versions['grammar']}")
         logger.error(msg)
         raise CompatibilityError(msg)

src/virtmat/language/utilities/formatters.py

@@ -7,6 +7,8 @@ import pint_pandas
 from virtmat.language.utilities import amml, chemistry
 from virtmat.language.utilities.types import ScalarReal, ScalarNumerical, NC
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 
 def formatter_pint(magnitude, unit):
     """format a pint quantity value"""

src/virtmat/language/utilities/serializable.py

@@ -16,6 +16,8 @@ from .errors import RuntimeTypeError
 from .units import ureg
 from .lists import list_flatten
 
+pint_pandas.pint_array.DEFAULT_SUBDTYPE = None
+
 DATA_SCHEMA_VERSION = 7