History object system

Overview

The History class stores internal variables of material models. Originally, NEML stored internal variables in a flat pointer array. This meant that the programmer or end user had to manually track which variable was located at which index in the array and, for non-scalar variables, correctly flatten and interpret the data.

The History class helps manage model internal variables. Fundamentally, it is a dictionary that returns and stores an internal variable associated with a string key naming the actual variable in the model implementation. The class also manages types so that it returns the correct type of object. For example, the History class could manage a "direction" internal variable with type Vector. The user can request the object return "direction" and the History object would return the correct Vector type.

Currently, the class is configured to store and return objects of the following types:

Internally, all of these classes are stored in a single flat array. The system can either manage its own memory (freeing it on deletion of the object) or accept a pointer to externally managed memory. For example, a finite element analysis program can pass in the material model history as a large array in memory and NEML can wrap that memory using the History class and give descriptive access to each variable without copying the underlying data. This allows for seamlessly converting a flat array containing the model internal variables into an instance of the History class without copying. It also allows the calling program to block the internal variables of several material points, potentially allowing the compiler to perform vector optimizations.

Oftentimes, implementations of material models will need to store the derivatives of a set of internal variables. The History class contains methods for duplicating a given History instance but changing the types (and corresponding storage) of the new instance to reflect the types appropriate for storing the derivative of the original History with respect to some other object type.

Class description

class History

Public Functions

History()

Default constructor (manage own memory)

History(bool store)

Default constructor (option to not manage memory)

History(const History &other)

Copy constructor.

History(const History &&other)

Move constructor.

History(double *data)

Dangerous constructor, only use if you know what you’re doing.

History(const double *data)

Dangerous constructor, only use if you know what you’re doing.

virtual ~History()

Destructor.

History &operator=(const History &other)

Copy.

History &operator=(const History &&other)

Move.

History deepcopy() const

Explicit deepcopy.

inline bool store() const

Do I own my own data?

inline const double *rawptr() const

Raw data pointer (const)

inline double *rawptr()

Raw data pointer (nonconst)

void set_data(double *input)

Set storage to some external pointer.

void copy_data(const double *const input)

Copy data from some external pointer.

size_t size() const

Size of storage required.

void make_store()

Convert to store.

template<typename T>
inline void add(std::string name)

Add a generic object.

void add(std::string name, StorageType type, size_t size)

Add known object.

template<class T>
inline item_return<T>::type get(std::string name) const

Get an item (provide with correct class)

inline double *get_data(std::string name)

Get a pointer to the raw location of an item.

inline const std::unordered_map<std::string, size_t> &get_loc() const

Get the location map.

inline const std::unordered_map<std::string, StorageType> &get_type() const

Get the type map.

inline const std::vector<std::string> &get_order() const

Get the name order.

inline std::unordered_map<std::string, size_t> &get_loc()

Get the location map.

inline std::unordered_map<std::string, StorageType> &get_type()

Get the type map.

inline std::vector<std::string> &get_order()

Get the order.

inline const std::vector<std::string> &items() const

Return all the items in this object.

size_t size_of_entry(std::string name) const

Helper to get the size of a particular object.

void resize(size_t inc)

Resize method.

void increase_store(size_t newsize)

Actually increase internal storage.

void scalar_multiply(double scalar)

Multiply everything by a scalar.

History &operator+=(const History &other)

Add another history to this one.

History &add_union(const History &other)

Combine another history object through a union.

History copy_blank(std::vector<std::string> exclude = {}) const

Make a blank copy.

void copy_maps(const History &other)

Copy over the order maps.

History &zero()

Make zero.

template<class T>
inline History derivative() const

Make a History appropriate to hold the derivatives of the indicated items.

History history_derivative(const History &other) const

Derivative with respect to a different history.

History split(std::vector<std::string> sep, bool after = true) const

Split a history in two.

History subset(std::vector<std::string> vars) const

Extract a subset.

History &reorder(std::vector<std::string> names)

Reorder based on the provided list of names.

inline bool contains(std::string name) const

Quick function to check to see if something is in the vector.

History postmultiply(const SymSymR4 &T)

Postmultiply by various objects.

void unravel_hh(const History &base, double *const array)

This unravels a history derivative into row major storage.

double *start_loc(std::string name)

Starting location of an entry.

std::vector<std::string> formatted_names() const

Nicely formatted names for the flat storage.

template<>
inline History::item_return<double>::type get(std::string name) const

Special case for a double.

template<>
inline History derivative() const

Special case for self derivative.

template<class T>
struct item_return

Helper for template magic.

template<>
struct item_return<double>