easyvvuq.data_structs

  1"""Data structures to ensure consistency during serialization for databases.
  2
  3"""
  4import os
  5import logging
  6import json
  7from easyvvuq import constants
  8from easyvvuq.utils.helpers import easyvvuq_serialize
  9import numpy
 10
 11__copyright__ = """
 12
 13    Copyright 2018 Robin A. Richardson, David W. Wright
 14
 15    This file is part of EasyVVUQ
 16
 17    EasyVVUQ is free software: you can redistribute it and/or modify
 18    it under the terms of the Lesser GNU General Public License as published by
 19    the Free Software Foundation, either version 3 of the License, or
 20    (at your option) any later version.
 21
 22    EasyVVUQ is distributed in the hope that it will be useful,
 23    but WITHOUT ANY WARRANTY; without even the implied warranty of
 24    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 25    Lesser GNU General Public License for more details.
 26
 27    You should have received a copy of the Lesser GNU General Public License
 28    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 29
 30"""
 31__license__ = "LGPL"
 32
 33logger = logging.getLogger(__name__)
 34
 35
 36def check_local_dir(path, dir_type='campaign'):
 37    """
 38    Check that local path exists and if not create it.
 39
 40    Parameters
 41    ----------
 42    path : str
 43        Directory location to check.
 44    dir_type : str, default='campaign'
 45        Type of directory we are checking (used for user and debugging
 46        information.)
 47
 48    Returns
 49    -------
 50
 51    """
 52
 53    if not os.path.isdir(path):
 54
 55        if os.path.exists(path):
 56            logger.critical(f'{path} specified as {dir_type} directory '
 57                            f'for local run but is not a directory.')
 58            raise IOError(f'Invalid {dir_type} directory')
 59        else:
 60            os.makedirs(path)
 61
 62
 63def check_reference(ref, run_name, ref_type='campaign'):
 64    """
 65    Validation check for a `RunInfo` reference. Checks that an integer value
 66    has been passed to use as a reference to another 'table' - i.e. to a
 67    specific campaign, app or sampler.
 68
 69    Parameters
 70    ----------
 71    ref : int
 72        Reference to be checked.
 73    run_name : str
 74        Name of run for which the check is being performed (user info/
 75        debugging).
 76    ref_type : str, default='campaign'
 77        Are we checking for a campaign, sampler or app (user info/
 78        debugging).
 79
 80    Returns
 81    -------
 82
 83    """
 84
 85    if ref is None:
 86        message = f'No {ref_type} id specified for run {run_name}'
 87        logger.critical(message)
 88        raise RuntimeError(message)
 89
 90    if not isinstance(ref, int):
 91        message = (f'Invalid {ref_type} id ({ref}) specified for '
 92                   f'run {run_name}')
 93        logger.critical(message)
 94        raise RuntimeError(message)
 95
 96
 97class RunInfo:
 98    """Handles information for individual application runs.
 99
100    Parameters
101    ----------
102    run_name : str
103        Human readable name of the run.
104    app : None or int
105        ID of the associated application.
106    params : None or dict
107        Dictionary of parameter values for this run.
108    sample: None or int
109        ID of the sampler that created the run.
110    campaign: None or int
111        ID of the associated campaign.
112
113    Attributes
114    ----------
115    campaign : int
116        ID of the associated campaign.
117    sample : int
118        ID of the sampler that created the run.
119    app : int
120        ID of the associated application.
121    run_name : str
122        Human readable name of the run.
123    status : enum(Status)
124    """
125
126    def __init__(
127            self,
128            run_name=None,
129            run_dir=None,
130            app=None,
131            params=None,
132            sample=None,
133            campaign=None,
134            status=constants.Status.NEW):
135
136        self.campaign = campaign
137        self.sample = sample
138        self.app = app
139        self.run_name = run_name
140        self.run_dir = run_dir
141
142        if not params:
143            message = f'No run configuration specified for run {run_name}'
144            raise RuntimeError(message)
145
146        self.params = params
147        self.status = status
148
149        self.iteration = 0
150
151    def to_dict(self, flatten=False):
152        """Convert to a dictionary (optionally flatten to single level)
153
154        Parameters
155        ----------
156        flatten : bool
157            Should the return dictionary be single level (i.e. should `params`
158            or other dictionary variables be serialized).
159
160        Returns
161        -------
162        dict
163            Dictionary representing the run - if flattened then params are
164            returned as a JSON format sting.
165        """
166
167        def convert_nonserializable(obj):
168            if isinstance(obj, numpy.int64):
169                return int(obj)
170            raise TypeError('Unknown type:', type(obj))
171
172        if flatten:
173
174            out_dict = {
175                'run_name': self.run_name,
176                'run_dir': self.run_dir,
177                'params': json.dumps(self.params, default=convert_nonserializable),
178                'status': constants.Status(self.status),
179                'campaign': self.campaign,
180                'sampler': self.sample,
181                'app': self.app,
182                'iteration': self.iteration,
183            }
184
185        else:
186
187            out_dict = {
188                'run_name': self.run_name,
189                'run_dir': self.run_dir,
190                'params': self.params,
191                'status': constants.Status(self.status),
192                'campaign': self.campaign,
193                'sampler': self.sample,
194                'app': self.app,
195                'iteration': self.iteration,
196            }
197
198        return out_dict
199
200
201class AppInfo:
202    """Handles information for particular application.
203
204    Attributes
205    ----------
206    name : str or None
207        Human readable application name.
208    paramsspec : ParamsSpecification or None
209        Description of possible parameter values.
210    """
211
212    def __init__(
213            self,
214            name=None,
215            paramsspec=None,
216            actions=None):
217
218        self.name = name
219        self.paramsspec = paramsspec
220        self.actions = actions
221
222    def to_dict(self, flatten=False):
223        """Convert to a dictionary (optionally flatten to single level)
224
225        Parameters
226        ----------
227        flatten : bool
228            Should the return dictionary be single level (i.e. should `paramsspec`
229            be serialized).
230
231        Returns
232        -------
233        dict
234            Dictionary representing the application- if flattened then `paramsspec`
235            is returned as a JSON format sting.
236        """
237
238        if flatten:
239
240            out_dict = self.to_dict()
241
242            out_dict['params'] = self.paramsspec.serialize()
243        else:
244
245            out_dict = {
246                'name': self.name,
247                'params': self.paramsspec,
248                'actions': easyvvuq_serialize(self.actions),
249            }
250
251        return out_dict
252
253
254class CampaignInfo:
255    """Handles information on Campaign.
256
257    Parameters
258    ----------
259    name : str or None
260        Human readable campaign name.
261    easyvvuq_version : str or None
262        Version of EasyVVUQ used to create the campaign.
263    campaign_dir_prefix : str or None
264        Prefix test for campaign directory.
265    campaign_dir : str or None,
266        Path to the campaign directory.
267    runs_dir : str or None
268        path to run directory (within the campaign directory)
269    local : bool, default=False
270        Is this campaign designed to be created and executed on the same
271        machine?
272
273    Attributes
274    ----------
275    name : str or None
276        Human readable campaign name.
277    easyvvuq_version : str or None
278        Version of EasyVVUQ used to create the campaign.
279    campaign_dir_prefix : str or None
280        Prefix test for campaign directory.
281    campaign_dir : str or None,
282        Path to the campaign directory.
283    runs_dir : str or None
284        path to run directory (within the campaign directory)
285    """
286
287    def __init__(self, name=None, easyvvuq_version=None,
288                 campaign_dir_prefix=None, campaign_dir=None,
289                 runs_dir=None, local=False):
290
291        if name is None:
292            message = "CampaignInfo constructor must be passed a 'name'."
293            logger.critical(message)
294            raise RuntimeError(message)
295
296        if campaign_dir is None:
297            message = "CampaignInfo constructor must be passed 'campaign_dir'"
298            logger.critical(message)
299            raise RuntimeError(message)
300
301        self.name = name
302        self.campaign_dir_prefix = campaign_dir_prefix
303
304        self.easyvvuq_version = easyvvuq_version
305
306        # TODO: think about right location for path check for remote runs
307        if local:
308            check_local_dir(campaign_dir)
309
310        self.campaign_dir = campaign_dir
311
312        if runs_dir is None:
313            runs_dir = os.path.join(campaign_dir, 'runs')
314
315        if local:
316            check_local_dir(runs_dir, 'runs')
317
318        self.runs_dir = runs_dir
319
320    @property
321    def easyvvuq_version(self):
322        return self._easyvvuq_version
323
324    @easyvvuq_version.setter
325    def easyvvuq_version(self, version_no):
326        # TODO: check validity and compatibility
327        self._easyvvuq_version = version_no
328
329    def to_dict(self, flatten=False):
330        """Convert this to a dictionary
331
332        Parameters
333        ----------
334        flatten : bool
335            Should the return dictionary be single level (always true here).
336
337        Returns
338        -------
339        dict
340            Dictionary representing the campaign.
341        """
342
343        out_dict = {
344            'name': self.name,
345            'campaign_dir': self.campaign_dir,
346            'campaign_dir_prefix': self.campaign_dir_prefix,
347            'runs_dir': self.runs_dir,
348            'easyvvuq_version': self.easyvvuq_version
349        }
350
351        return out_dict