inp Namespace Reference

Collection of methods and database related to input. More...

Data Structures
struct	Accepts
	What a field accepts. More...
struct	BCBaseDeck
	User-input data for particle neighbor search. More...
struct	BCDeck
	Structure to read and store test-related input data. More...
struct	ContactDeck
	Structure to read and store particle-particle contact related input data. More...
struct	ContactPairDeck
	Structure to read and store particle-particle contact related input data. More...
struct	Field
	One field of a deck, declared once. More...
class	Input
	A class to read input file. More...
struct	MatData
	Structure for elastic properties and fracture properties. More...
struct	MaterialDeck
	Structure to read and store material related data. More...
struct	MeshDeck
	Structure to read and store mesh related input data. More...
struct	ModelDeck
	Structure to read and store model related input data. More...
struct	OneOf
	A quantity that can be given in more than one way. More...
struct	OutputDeck
	Structure to read input data for performing simulation output. More...
struct	ParticleDeck
	Structure to read and store particle related input data. More...
struct	PGenDeck
	Structure to read and store particle generation data, such as particle locations and group file. More...
struct	PNeighborDeck
	User-input data for particle neighbor search. More...
struct	RestartDeck
	Structure to read and store restart related data input. More...
struct	TestDeck
	Structure to read and store test-related input data. More...

Functions
template<class T >
std::string	typeName ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< bool > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< int > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< std::size_t > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< double > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< std::string > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< std::vector< double > > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< std::vector< std::string > > ()
	Name of the type of a field, reported by the schema.
template<>
std::string	typeName< std::vector< std::size_t > > ()
	Name of the type of a field, reported by the schema.
template<class T >
void	printValue (std::ostringstream &oss, const T &v)
	Appends a value to a stream.
template<class T >
void	printValue (std::ostringstream &oss, const std::vector< T > &v)
	Appends the entries of a vector, separated by commas.
template<class Deck , class T >
Field< Deck >	field (T Deck::*m, std::string key, T def, std::string doc, Accepts< T > accepts={}, std::function< bool(const T &)> emitIf=[](const T &) { return true;})
	Declares a field that maps one key to one member.
template<class Deck , class T >
Field< Deck >	requiredField (T Deck::*m, std::string key, std::string doc, Accepts< T > accepts={})
	Declares a field that has no default and must be present.
template<class Deck >
void	readFields (Deck &d, const json &j, const std::vector< Field< Deck > > &fs)
	Reads every field of the table from the block.
template<class Deck >
void	writeFields (const Deck &d, json &j, const std::vector< Field< Deck > > &fs)
	Writes every field of the table into the block.
template<class Deck >
void	printFields (const Deck &d, std::ostringstream &oss, const std::vector< Field< Deck > > &fs, const std::string &tab="")
	Appends every field of the table to a stream.
template<class Deck >
json	defaultsJson (const std::vector< Field< Deck > > &fs)
	The block with every field at its default.
template<class Deck >
json	schemaJson (const std::vector< Field< Deck > > &fs)
	Key, type, default and description of every field.
void	checkGroups (const json &block, const std::vector< OneOf > &groups)
	Checks that each group has exactly one of its keys.
std::size_t	editDistance (const std::string &a, const std::string &b)
	Number of single character edits between two strings.
void	checkNames (const json &given, const std::vector< std::string > &names)
	Rejects a key that is not among those named.
template<class Deck >
void	checkKeys (const json &given, const std::vector< Field< Deck > > &fs, const std::vector< std::string > &extra={})
	Rejects a key that no field declares.
template<class Deck >
json	applyGiven (const json &given, const std::vector< Field< Deck > > &fs, const std::vector< std::string > &extra={})
	The default block with the given keys replaced.

Detailed Description

Collection of methods and database related to input.

This namespace provides methods and data members specific to reading input data. We partition the input data into number of small collection of input data referred to as decks, e.g. inp::FractureDeck, inp::MeshDeck, etc. We use structs to define the deck.

• Each deck is unique and is designed to initialize the higher level object associated to it without needing information from other decks. For example, mesh::Mesh is initialized by inp::MeshDeck.

The namespace consists of Input and Policy member classes. Input class is the main class responsible of reading input data into the decks.

Function Documentation

applyGiven()

template<class Deck >

json inp::applyGiven	(	const json &	given,
		const std::vector< Field< Deck > > &	fs,
		const std::vector< std::string > &	extra = {}
	)

The default block with the given keys replaced.

The name of every key and the value of every field are checked here, so that a deck is rejected where it is built rather than where it is read.

Parameters

given	Keys and values to replace, checked against the table
fs	Field table of the deck
extra	Keys the deck reads outside the table

Returns

j The block

Definition at line 443 of file deckField.h.

                                                    {}) {
  checkKeys(given, fs, extra);
  json j = defaultsJson(fs);
  if (!given.is_object())
    return j;
 
  for (const auto &item : given.items()) {
    bool emit = true;
    for (const auto &f : fs)
      if (f.key == item.key()) {
        f.check(item.value());
        emit = f.emit(item.value());
      }
    // A field that is not written at its default is not written when the
    // same value is given, so that the block does not depend on whether the
    // caller named the field.
    if (emit)
      j[item.key()] = item.value();
    else
      j.erase(item.key());
  }
  return j;
}

Referenced by inp::ContactDeck::getExampleJson(), inp::ContactPairDeck::getExampleJson(), inp::MaterialDeck::getExampleJson(), inp::MeshDeck::getExampleJson(), inp::ModelDeck::getExampleJson(), inp::OutputDeck::getExampleJson(), inp::PGenDeck::getExampleJson(), inp::PNeighborDeck::getExampleJson(), inp::RestartDeck::getExampleJson(), inp::TestDeck::getExampleJson(), inp::BCBaseDeck::getExampleJson(), anonymous_namespace{testDeckField.cpp}::testKeysAreNamed(), anonymous_namespace{testDeckField.cpp}::testReadAndWrite(), and anonymous_namespace{testDeckField.cpp}::testValuesCheckedWhenBuilt().

Here is the caller graph for this function:

checkGroups()

void inp::checkGroups ( const json &  block, const std::vector< OneOf > &  groups  )

inline

Checks that each group has exactly one of its keys.

Parameters

block	The block to check
groups	Groups of the deck

Definition at line 317 of file deckField.h.

                                                                           {
  for (const auto &g : groups) {
    std::vector<std::string> present;
    for (const auto &k : g.keys)
      if (block.find(k) != block.end())
        present.push_back(k);
 
    if (present.size() == 1 || (present.empty() && !g.required))
      continue;
 
    std::ostringstream oss;
    oss << "Error: give exactly one of";
    for (const auto &k : g.keys)
      oss << " " << k;
    oss << " for " << g.what << ". ";
    if (present.empty())
      oss << "None was given.\n";
    else {
      oss << "These were given:";
      for (const auto &k : present)
        oss << " " << k;
      oss << ".\n";
    }
    throw std::runtime_error(oss.str());
  }
}

Referenced by inp::ContactPairDeck::getExampleJson(), inp::MaterialDeck::getExampleJson(), inp::ContactPairDeck::readFromJson(), inp::MaterialDeck::readFromJson(), and anonymous_namespace{testDeckField.cpp}::testGroups().

Here is the caller graph for this function:

checkKeys()

template<class Deck >

void inp::checkKeys	(	const json &	given,
		const std::vector< Field< Deck > > &	fs,
		const std::vector< std::string > &	extra = {}
	)

Rejects a key that no field declares.

Parameters

given	Keys the caller supplied
fs	Field table of the deck
extra	Keys the deck reads outside the table

Definition at line 421 of file deckField.h.

                                                   {}) {
  std::vector<std::string> names;
  names.reserve(fs.size() + extra.size());
  for (const auto &f : fs)
    names.push_back(f.key);
  names.insert(names.end(), extra.begin(), extra.end());
  checkNames(given, names);
}

Referenced by inp::ContactPairDeck::getExampleJson(), and inp::BCBaseDeck::getExampleJson().

Here is the caller graph for this function:

checkNames()

void inp::checkNames ( const json &  given, const std::vector< std::string > &  names  )

inline

Rejects a key that is not among those named.

A deck is built by naming keys. A key that is not declared would otherwise be dropped without a message, and the run would proceed with the default in place of the value the caller asked for. A key within an edit distance of three of a declared one is reported together with that name.

Parameters

given	Keys the caller supplied
names	Every key the deck accepts

Definition at line 379 of file deckField.h.

                                                          {
  if (given.is_null() || given.empty())
    return;
  if (!given.is_object())
    throw std::runtime_error(
        "Error: deck values must be given as name and value pairs.\n");
 
  for (const auto &item : given.items()) {
    const std::string key = item.key();
    if (std::find(names.begin(), names.end(), key) != names.end())
      continue;
 
    std::string closest;
    std::size_t best = std::string::npos;
    for (const auto &n : names) {
      const std::size_t d = editDistance(key, n);
      if (d < best) {
        best = d;
        closest = n;
      }
    }
    std::ostringstream oss;
    oss << "Error: no field named " << key << ".";
    if (best <= 3)
      oss << " Closest declared field is " << closest << ".";
    oss << "\nDeclared fields are:";
    for (const auto &n : names)
      oss << " " << n;
    oss << "\n";
    throw std::runtime_error(oss.str());
  }
}

References editDistance().

Referenced by inp::BCDeck::getExampleJson(), and inp::MeshDeck::getExampleJson().

Here is the call graph for this function:

Here is the caller graph for this function:

defaultsJson()

template<class Deck >

json inp::defaultsJson

(

const std::vector< Field< Deck > > &

fs

)

The block with every field at its default.

Definition at line 260 of file deckField.h.

                                                    {
  json j = json::object();
  for (const auto &f : fs)
    f.writeDefault(j);
  return j;
}

Referenced by schemaJson(), and anonymous_namespace{testDeckField.cpp}::testDefaultsAndSchema().

Here is the caller graph for this function:

editDistance()

std::size_t inp::editDistance ( const std::string &  a, const std::string &  b  )

inline

Number of single character edits between two strings.

Used to name the closest key when a caller supplies one that is not declared.

Parameters

a	First string
b	Second string

Returns

n Edit distance

Definition at line 354 of file deckField.h.

                                                                      {
  std::vector<std::size_t> prev(b.size() + 1), cur(b.size() + 1);
  for (std::size_t j = 0; j <= b.size(); ++j)
    prev[j] = j;
  for (std::size_t i = 1; i <= a.size(); ++i) {
    cur[0] = i;
    for (std::size_t j = 1; j <= b.size(); ++j)
      cur[j] = std::min({prev[j] + 1, cur[j - 1] + 1,
                         prev[j - 1] + (a[i - 1] == b[j - 1] ? 0 : 1)});
    prev = cur;
  }
  return prev[b.size()];
}

Referenced by checkNames(), and anonymous_namespace{testDeckField.cpp}::testEditDistance().

Here is the caller graph for this function:

field()

template<class Deck , class T >

Field< Deck > inp::field	(	T Deck::*	m,
		std::string	key,
		T	def,
		std::string	doc,
		Accepts< T >	accepts = {},
		std::function< bool(const T &)>	emitIf = [](const T &) { return true; }
	)

Declares a field that maps one key to one member.

Parameters

m	Pointer to the member
key	Key in the JSON block
def	Value used when the key is absent
doc	One line describing the field
accepts	What the field accepts
emitIf	Written only when this is true of the value. Use it for a key the deck omits rather than writes at its default, such as Horizon, which is absent when the horizon is set by Horizon_Mesh_Ratio instead

Returns

field The field

Definition at line 144 of file deckField.h.

                         {},
    std::function<bool(const T &)> emitIf = [](const T &) { return true; }) {
 
  // Accepted values and bounds apply to the scalar types. A field holding a
  // list is checked by the deck if it needs to be.
  constexpr bool checkable =
      std::is_arithmetic_v<T> || std::is_same_v<T, std::string>;
 
  auto check = [key, accepts](const T &v) {
    if constexpr (checkable) {
      if (!accepts.values.empty() &&
          std::find(accepts.values.begin(), accepts.values.end(), v) ==
              accepts.values.end()) {
        std::ostringstream oss;
        oss << "Error: " << key << " must be one of:";
        for (const auto &a : accepts.values)
          oss << " " << a;
        oss << ". Given value is " << v << ".\n";
        throw std::runtime_error(oss.str());
      }
      if (accepts.min.has_value() && v < accepts.min.value()) {
        std::ostringstream oss;
        oss << "Error: " << key << " must be at least " << accepts.min.value()
            << ". Given value is " << v << ".\n";
        throw std::runtime_error(oss.str());
      }
      if (accepts.max.has_value() && accepts.max.value() < v) {
        std::ostringstream oss;
        oss << "Error: " << key << " must be at most " << accepts.max.value()
            << ". Given value is " << v << ".\n";
        throw std::runtime_error(oss.str());
      }
    }
  };
 
  return Field<Deck>{
      key, std::move(doc), typeName<T>(),
      [m, key, def, check](Deck &d, const json &j) {
        d.*m = j.value(key, def);
        check(d.*m);
      },
      [m, key, emitIf](const Deck &d, json &j) {
        if (emitIf(d.*m))
          j[key] = d.*m;
      },
      [key, def, emitIf](json &j) {
        if (emitIf(def))
          j[key] = def;
      },
      [m, key](const Deck &d, std::ostringstream &oss,
               const std::string &tab) {
        oss << tab << key << " = ";
        printValue(oss, d.*m);
        oss << std::endl;
      },
      [check](const json &v) { check(v.get<T>()); },
      [emitIf](const json &v) { return emitIf(v.get<T>()); }};
}

Referenced by inp::MeshDeck::createMeshFields(), inp::BCBaseDeck::fields(), inp::ContactDeck::fields(), inp::ContactPairDeck::fields(), inp::MatData::fields(), inp::MaterialDeck::fields(), inp::MeshDeck::fields(), inp::ModelDeck::fields(), inp::OutputDeck::fields(), inp::PGenDeck::fields(), inp::PNeighborDeck::fields(), inp::RestartDeck::fields(), inp::TestDeck::fields(), anonymous_namespace{testDeckField.cpp}::SampleDeck::fields(), inp::MaterialDeck::influenceFields(), inp::BCBaseDeck::spatialFunctionFields(), and inp::BCBaseDeck::timeFunctionFields().

Here is the caller graph for this function:

printFields()

template<class Deck >

void inp::printFields	(	const Deck &	d,
		std::ostringstream &	oss,
		const std::vector< Field< Deck > > &	fs,
		const std::string &	tab = ""
	)

Appends every field of the table to a stream.

Parameters

d	The deck
oss	Stream to append to
fs	Field table of the deck
tab	Prefix written before each field

Definition at line 251 of file deckField.h.

                                            {
  for (const auto &f : fs)
    f.print(d, oss, tab);
}

Referenced by inp::ContactDeck::printStr(), inp::MeshDeck::printStr(), inp::ModelDeck::printStr(), inp::OutputDeck::printStr(), inp::PGenDeck::printStr(), inp::PNeighborDeck::printStr(), inp::RestartDeck::printStr(), inp::TestDeck::printStr(), and anonymous_namespace{testDeckField.cpp}::testPrint().

Here is the caller graph for this function:

printValue() [1/2]

template<class T >

void inp::printValue	(	std::ostringstream &	oss,
		const std::vector< T > &	v
	)

Appends the entries of a vector, separated by commas.

Definition at line 107 of file deckField.h.

                                                              {
  oss << util::io::printStr<T>(v, 0);
}

printValue() [2/2]

template<class T >

void inp::printValue	(	std::ostringstream &	oss,
		const T &	v
	)

Appends a value to a stream.

Definition at line 101 of file deckField.h.

                                                   {
  oss << v;
}

readFields()

template<class Deck >

void inp::readFields	(	Deck &	d,
		const json &	j,
		const std::vector< Field< Deck > > &	fs
	)

Reads every field of the table from the block.

Definition at line 230 of file deckField.h.

                                                                          {
  for (const auto &f : fs)
    f.read(d, j);
}

Referenced by inp::ContactDeck::readFromJson(), inp::ContactPairDeck::readFromJson(), inp::MatData::readFromJson(), inp::MaterialDeck::readFromJson(), inp::MeshDeck::readFromJson(), inp::ModelDeck::readFromJson(), inp::OutputDeck::readFromJson(), inp::PGenDeck::readFromJson(), inp::PNeighborDeck::readFromJson(), inp::RestartDeck::readFromJson(), inp::TestDeck::readFromJson(), inp::BCBaseDeck::readFromJson(), anonymous_namespace{testDeckField.cpp}::testAccepted(), and anonymous_namespace{testDeckField.cpp}::testReadAndWrite().

Here is the caller graph for this function:

requiredField()

template<class Deck , class T >

Field< Deck > inp::requiredField	(	T Deck::*	m,
		std::string	key,
		std::string	doc,
		Accepts< T >	accepts = {}
	)

Declares a field that has no default and must be present.

Parameters

m	Pointer to the member
key	Key in the JSON block
doc	One line describing the field
accepts	What the field accepts

Returns

field The field

Definition at line 215 of file deckField.h.

                                               {}) {
  auto f = field(m, key, T{}, std::move(doc), accepts);
  f.read = [m, key, accepts, f](Deck &d, const json &j) {
    if (j.find(key) == j.end())
      throw std::runtime_error("Error: " + key + " is required.\n");
    json one = json::object();
    one[key] = j.at(key);
    f.read(d, one);
  };
  return f;
}

schemaJson()

template<class Deck >

json inp::schemaJson

(

const std::vector< Field< Deck > > &

fs

)

Key, type, default and description of every field.

The Python interface builds its arguments from this, so that a field added to the table needs no change on the Python side.

Parameters

fs	Field table of the deck

Returns

schema One object per field

Definition at line 276 of file deckField.h.

                                                                        {
  json out = json::array();
  const json defaults = defaultsJson(fs);
  for (const auto &f : fs) {
    json entry = {{"key", f.key}, {"type", f.type}, {"doc", f.doc}};
    if (defaults.find(f.key) != defaults.end())
      entry["default"] = defaults.at(f.key);
    out.push_back(entry);
  }
  return out;
}

References defaultsJson().

Referenced by anonymous_namespace{testDeckField.cpp}::testDefaultsAndSchema().

Here is the call graph for this function:

Here is the caller graph for this function:

typeName()

template<class T >

std::string inp::typeName ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 75 of file deckField.h.

{ return "value"; }

typeName< bool >()

template<>

std::string inp::typeName< bool > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 77 of file deckField.h.

{ return "bool"; }

typeName< double >()

template<>

std::string inp::typeName< double > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 83 of file deckField.h.

{ return "double"; }

typeName< int >()

template<>

std::string inp::typeName< int > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 79 of file deckField.h.

{ return "int"; }

typeName< std::size_t >()

template<>

std::string inp::typeName< std::size_t > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 81 of file deckField.h.

{ return "size_t"; }

typeName< std::string >()

template<>

std::string inp::typeName< std::string > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 85 of file deckField.h.

{ return "string"; }

typeName< std::vector< double > >()

template<>

std::string inp::typeName< std::vector< double > > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 87 of file deckField.h.

                                                           {
  return "double[]";
}

typeName< std::vector< std::size_t > >()

template<>

std::string inp::typeName< std::vector< std::size_t > > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 95 of file deckField.h.

                                                              {
  return "size_t[]";
}

typeName< std::vector< std::string > >()

template<>

std::string inp::typeName< std::vector< std::string > > ( )

inline

Name of the type of a field, reported by the schema.

Definition at line 91 of file deckField.h.

                                                              {
  return "string[]";
}

writeFields()

template<class Deck >

void inp::writeFields	(	const Deck &	d,
		json &	j,
		const std::vector< Field< Deck > > &	fs
	)

Writes every field of the table into the block.

Definition at line 237 of file deckField.h.

                                                                           {
  for (const auto &f : fs)
    f.write(d, j);
}

Referenced by anonymous_namespace{testDeckField.cpp}::testReadAndWrite(), inp::PGenDeck::writeToJson(), inp::PNeighborDeck::writeToJson(), and inp::RestartDeck::writeToJson().

Here is the caller graph for this function: