fennol.utils.input_parser

  1"""
  2FeNNol Input Parameter Parser
  3
  4This module provides parsing capabilities for FeNNol input files in .fnl format.
  5It supports hierarchical parameter organization, automatic unit conversion,
  6and various data types including booleans, numbers, strings, and lists.
  7
  8The main components are:
  9- InputFile: Dictionary-like container for hierarchical parameters
 10- parse_input: Parser function for .fnl files  
 11- convert_dict_units: Unit conversion utility for YAML/dict inputs
 12
 13Supported input formats:
 14- .fnl: Native FeNNol format with hierarchical sections
 15- .yaml/.yml: YAML format (processed through convert_dict_units)
 16
 17Unit conversion:
 18- Units specified in brackets: dt[fs] = 0.5
 19- Units specified in braces: gamma{THz} = 10.0
 20- All units converted to atomic units internally
 21
 22Boolean representations:
 23- True: true, yes, .true.
 24- False: false, no, .false.
 25
 26"""
 27
 28import re
 29from typing import Dict, Any
 30from .atomic_units import au,UnitSystem
 31
 32_separators = " |,|=|\t|\n"
 33_comment_chars = ["#", "!"]
 34_true_repr = ["true", "yes", ".true."]
 35_false_repr = ["false", "no", ".false."]
 36
 37
 38class InputFile(dict):
 39    """
 40    Dictionary-like container for hierarchical input parameters.
 41    
 42    This class extends dict to provide path-based access to nested parameters
 43    using '/' as a separator. It supports case-insensitive keys and automatic
 44    unit conversion from parameter names with bracket notation.
 45    
 46    Attributes:
 47        case_insensitive (bool): Whether keys are case-insensitive (default: True)
 48    
 49    Examples:
 50        >>> params = InputFile()
 51        >>> params.store("xyz_input/file", "system.xyz")
 52        >>> params.get("xyz_input/file")
 53        'system.xyz'
 54        >>> params["temperature"] = 300.0
 55        >>> params.get("temperature")
 56        300.0
 57    """
 58    case_insensitive = True
 59
 60    def __init__(self, *args, **kwargs):
 61        super(InputFile, self).__init__(*args, **kwargs)
 62        if InputFile.case_insensitive:
 63            for key in list(self.keys()):
 64                dict.__setitem__(self, key.lower(), dict.get(self, key))
 65        for key in list(self.keys()):
 66            if isinstance(self[key], dict):
 67                dict.__setitem__(self, key, InputFile(**self[key]))
 68        
 69
 70    def get(self, path, default=None):
 71        if not isinstance(path, str):
 72            raise TypeError("Path must be a string")
 73        if InputFile.case_insensitive:
 74            path = path.lower()
 75        keys = path.split("/")
 76        val = None
 77        for key in keys:
 78            if isinstance(val, InputFile):
 79                val = val.get(key, default=None)
 80            else:
 81                val = dict.get(self, key, None)
 82
 83            if val is None:
 84                return default
 85
 86        return val
 87
 88    def store(self, path, value):
 89        if not isinstance(path, str):
 90            raise TypeError("Path must be a string")
 91        if isinstance(value, dict):
 92            value = InputFile(**value)
 93        if InputFile.case_insensitive:
 94            path = path.lower()
 95        keys = path.split("/")
 96        child = self.get(keys[0], default=None)
 97        if isinstance(child, InputFile):
 98            if len(keys) == 1:
 99                print("Warning: overriding a sub-dictionary!")
100                dict.__setitem__(self, keys[0], value)
101                # self[keys[0]] = value
102                return 1
103            else:
104                child.store("/".join(keys[1:]), value)
105        else:
106            if len(keys) == 1:
107                dict.__setitem__(self, keys[0], value)
108                # self[keys[0]] = value
109                return 0
110            else:
111                if child is None:
112                    sub_dict = InputFile()
113                    sub_dict.store("/".join(keys[1:]), value)
114                    dict.__setitem__(self, keys[0], sub_dict)
115                else:
116                    print("Error: hit a leaf before the end of path!")
117                    return -1
118    
119    def __getitem__(self, path):
120        return self.get(path)
121    
122    def __setitem__(self, path, value):
123        return self.store(path, value)
124
125    def print(self, tab=""):
126        string = ""
127        for p_id, p_info in self.items():
128            string += tab + p_id
129            val = self.get(p_id)
130            if isinstance(val, InputFile):
131                string += "{\n" + val.print(tab=tab + "  ") + "\n" + tab + "}\n\n"
132            else:
133                string += " = " + str(val) + "\n"
134        return string[:-1]
135
136    def save(self, filename):
137        with open(filename, "w") as f:
138            f.write(self.print())
139
140    def __str__(self):
141        return self.print()
142
143
144def parse_input(input_file,us:UnitSystem=au):
145    """
146    Parse a FeNNol input file (.fnl format) into a hierarchical parameter structure.
147    
148    The parser supports:
149    - Hierarchical sections using curly braces {}
150    - Comments starting with # or !
151    - Unit specifications in brackets [unit] => converted to provided UnitSystem (default: atomic units)
152    - Boolean values (yes/no, true/false, .true./.false.)
153    - Numeric values (int/float)
154    - String values
155    - Lists of values
156    
157    Parameters:
158        input_file (str): Path to the input file
159        
160    Returns:
161        InputFile: Hierarchical dictionary containing parsed parameters
162        
163    Example input file::
164    
165        device cuda:0
166        temperature = 300.0
167        dt[fs] = 0.5
168        
169        xyz_input{
170            file system.xyz
171            indexed yes
172        }
173        
174        thermostat LGV
175        gamma[THz] = 10.0
176    """
177    f = open(input_file, "r")
178    struct = InputFile()
179    path = []
180    for line in f:
181        # remove all after comment character
182        for comment_char in _comment_chars:
183            index = line.find(comment_char)
184            if index >= 0:
185                line = line[:index]
186
187        # split line using defined separators
188        parsed_line = re.split(_separators, line.strip())
189
190        # remove empty strings
191        parsed_line = [x for x in parsed_line if x]
192        # skip blank lines
193        if not parsed_line:
194            continue
195        # print(parsed_line)
196
197        word0 = parsed_line[0].lower()
198        cat_fields = "".join(parsed_line)
199        # check if beginning of a category
200        if cat_fields.endswith("{"):
201            path.append(cat_fields[:-1])
202            continue
203        if cat_fields.startswith("&"):
204            path.append(cat_fields[1:])
205            continue
206        if cat_fields.endswith("{}"):
207            struct.store("/".join("path") + "/" + cat_fields[1:-2], InputFile())
208            continue
209
210        # print(current_category)
211        # if not path:
212        # 	print("Error: line not recognized!")
213        # 	return None
214        # else: #check if end of a category
215        if (cat_fields[0] in "}/") or ("&end" in cat_fields):
216            del path[-1]
217            continue
218
219        word0, unit = _get_unit_from_key(word0,us)
220        val = None
221        if len(parsed_line) == 1:
222            val = True  # keyword only => store True
223        elif len(parsed_line) == 2:
224            val = string_to_true_type(parsed_line[1], unit)
225        else:
226            # analyze parsed line
227            val = []
228            for word in parsed_line[1:]:
229                val.append(string_to_true_type(word, unit))
230        struct.store("/".join(path + [word0]), val)
231
232    f.close()
233    return struct
234
235
236def string_to_true_type(word, unit=None):
237    if unit is not None:
238        return float(word) / unit
239
240    try:
241        val = int(word)
242    except ValueError:
243        try:
244            val = float(word)
245        except ValueError:
246            if word.lower() in _true_repr:
247                val = True
248            elif word.lower() in _false_repr:
249                val = False
250            else:
251                val = word
252    return val
253
254
255def _get_unit_from_key(word:str,us:UnitSystem):
256    unit_start = max(word.find("{"), word.find("["))
257    n = len(word)
258    if unit_start < 0:
259        key = word
260        unit = None
261    elif unit_start == 0:
262        print("Error: Field '" + str(word) + "' must not start with '{' or '[' !")
263        raise ValueError
264    else:
265        if word[unit_start] == "{":
266            end_bracket = "}"
267        else:
268            end_bracket = "]"
269        key = word[:unit_start]
270        if word[n - 1] != end_bracket:
271            print("Error: wrong unit specification in field '" + str(word) + "' !")
272            raise ValueError
273
274        if n - unit_start - 2 < 0:
275            unit = 1.0
276        else:
277            unit = us.get_multiplier(word[unit_start + 1 : -1])
278            # print(key+" unit= "+str(unit))
279    return key, unit
280
281
282def convert_dict_units(d: Dict[str, Any],us:UnitSystem=au) -> Dict[str, Any]:
283    """
284    Convert all values in a dictionary from specified units to the provided unit system (atomic units by default).
285    
286    This function recursively processes a dictionary and converts any values
287    with unit specifications (indicated by keys containing [unit] or {unit})
288    to atomic units. The unit specification is removed from the key name.
289    
290    Parameters:
291        d (Dict[str, Any]): Dictionary with potentially unit-specified keys
292        
293    Returns:
294        Dict[str, Any]: Dictionary with values converted to atomic units
295        
296    Examples:
297        >>> d = {"dt[fs]": 0.5, "temperature": 300.0}
298        >>> convert_dict_units(d)
299        {"dt": 20.67..., "temperature": 300.0}
300    """
301
302    if not isinstance(d, dict):
303        raise TypeError("Input must be a dictionary")
304    if not d:
305        return d
306    if not isinstance(us, UnitSystem):
307        raise TypeError("Unit system must be an instance of UnitSystem")
308    d2 = {}
309    for k,v in d.items():
310        if isinstance(v, dict):
311            d2[k] = convert_dict_units(v,us)
312            continue
313        key, unit = _get_unit_from_key(k,us)
314        if unit is None:
315            d2[k] = v
316            continue
317        try:
318            if isinstance(v, list):
319                d2[key] = [x / unit for x in v]
320            elif isinstance(v, tuple):
321                d2[key] = tuple(x / unit for x in v)
322            else:
323                d2[key] = v / unit
324        except TypeError:
325            raise ValueError(f"Error: cannot convert value '{v}' of type to atomic units.")
326        except Exception as e:
327            print(f"Error: unexpected error in unit conversion for key '{k}': {e}")
328            raise e
329
330    return d2