From 360aed021b7b83ebb3db3dfed45f98af1f90c13d Mon Sep 17 00:00:00 2001 From: Mitchell Young Date: Thu, 16 Jan 2020 11:31:42 -0800 Subject: [PATCH] Add docs about database versions --- armi/bookkeeping/db/__init__.py | 30 +++++++++++++++++++++++++++++- armi/bookkeeping/db/database3.py | 12 ++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/armi/bookkeeping/db/__init__.py b/armi/bookkeeping/db/__init__.py index acfc736ae..c51da56ce 100644 --- a/armi/bookkeeping/db/__init__.py +++ b/armi/bookkeeping/db/__init__.py @@ -20,7 +20,35 @@ The database can be visualized through various tools such as XTVIEW. -This module contains factories for selecting and building DB-related objects +This module contains factories for selecting and building DB-related objects. + +Some notes on versions +---------------------- +Persistent storage of ARMI models has seen many changes throughout the years. +Calculation results were originally stored on a SQL database (version 1), which has been +fully deprecated at this point. + +Version 2 was the first to use HDF5 as the primary storage format. This was beneficial, +as it did not rely on any external infrastructure to operate, and benefited from the +suite of tools that help interact with HDF5 files. It was eventually replaced because +it did not store a complete model of the reactor, but rather a ghost of assembly, block, +and reactor parameters that could be applied to an existing reactor model (so long as +the dimensions were consistent!). This led to loading reactors being inconvenient and +error-prone, and also posed a limitation for representing more complex systems that have +non-core components. + +Version 3 was created to make the schema more flexible and to permit storing the entire +reactor model within the HDF5 file. All objects in the ARMI Composite Model are written +to the database, and the model can be recovered in its entirety just from the HDF5 file. +Since it's inception, it has seen a number of tweaks to improve its functionality and +fix bugs. + +Being a serialization format, the code associated with reading and writing database +files may not benefit from Don't Repeat Yourself (DRY) practices in the same way as +other code. Therefore, we do not share much code between different major versions of the +databases. Minor revisions (e.g. M.(N+1)) to the database structure should be simple +enough that specialized logic can be used to support all minor versions without posing a +maintenance burden. A detailed change log should be maintained of each minor revision. """ import os from typing import Optional, List, Tuple diff --git a/armi/bookkeeping/db/database3.py b/armi/bookkeeping/db/database3.py index 31f263b61..df596bbe4 100644 --- a/armi/bookkeeping/db/database3.py +++ b/armi/bookkeeping/db/database3.py @@ -32,6 +32,18 @@ for a given object or collection of object from the database file. When interacting with the database file, the ``Layout`` class is used to help map the hierarchical Composite Reactor Model to the flat representation in the database. + +Minor revision changelog +------------------------ + - 3.1: Improve the handling of reading/writing grids. + + - 3.2: Change the strategy for storing large attributes from using an Object Reference + to an external dataset to using a special string starting with an "@" symbol (e.g., + "@/c00n00/attrs/5_linkedDims"). This was done to support copying time node datasets + from one file to another without invalidating the references. Support is maintained + for reading previous versions, and for performing a ``mergeHistory()`` and converting + to the new reference strategy, but the old version cannot be written. + """ import collections import copy