Represents the ionic model and plug-in (IMP) data structure. More...

#include <ION_IF.h>

Inheritance diagram for limpet::IonIfBase:

Collaboration diagram for limpet::IonIfBase:

Public Member Functions
	IonIfBase (const IonType &type, Target target, node_count_t num_node, const std::vector< std::reference_wrapper< IonType >> &plugins)
	Constructor for IonIfBase. More...

virtual	~IonIfBase ()
	Virtual destructor declaration. More...

const IonType &	get_type () const
	Gets this IMP's model type. More...

node_count_t	get_num_node () const
	Gets the number of nodes handled by this IMP. More...

std::size_t	get_num_threads () const
	Gets the number of threads used for running this IMP. More...

IonIfBase *	parent () const
	Gets the parent IMP. More...

void	set_parent (IonIfBase *parent)

std::vector< IonIfBase * > &	plugins ()
	Returns a vector containing the plugins of this IMP. More...

uint32_t	get_reqdat () const
	Gets the data flags for this IMP's required data. More...

uint32_t	get_moddat () const
	Gets the data flags for this IMP's modified data. More...

void	set_moddat (uint32_t data)
	Set the data flag for this IMP's modified data. More...

cell_geom &	cgeom ()
	Gets the cell geometry data. More...

float	get_dt () const
	Gets the basic integration time step. More...

void	set_dt (float dt)
	Sets the basic integration time step. More...

ts &	get_tstp ()
	Gets the time stepper. More...

virtual void *	get_sv_address ()=0
	Gets the raw address of the state variables for this IMP. More...

virtual std::size_t	get_sv_size () const =0
	Gets the size of the structure this IMP uses for state variables. More...

std::vector< LUT > &	tables ()
	Gets the array of state variables. More...

LUT *	tables_d () const
	Gets an array of LUTs. More...

size_t	get_n_tables_d () const
	Gets the size of the array returned by IonIf::tables_d. More...

Target	get_target () const

virtual void	set_target (Target target)

void	initialize_params ()
	Initializes user modifiable parameters with default values defined in the respective ionic models. More...

virtual void	initialize (double dt, GlobalData_t **impdat)
	Initializes lookup table and state variable tables. More...

void	compute (node_index_t start, node_index_t end, GlobalData_t **data)
	Perform ionic model computation for 1 time step. More...

char *	fill_buf (char buf, int n, opencarp::Salt_list *l) const
	Appends the state variables to a buffer. More...

node_count_t	restore (opencarp::FILE_SPEC in, node_count_t n, const node_index_t pos, IIF_Mask_t mask, size_t offset, IMPinfo impinfo, const global_node_index_t *loc2canon)
	Reads in the state variables for an IMP. More...

node_count_t	restore_per_node (opencarp::FILE_SPEC in, node_count_t n, const node_index_t pos, IIF_Mask_t mask, size_t offset, IMPinfo impinfo, const global_node_index_t *loc2canon)
	Reads in the state variables for an IMP from a per-node (format >= 3) dump. More...

void	get_sv_layout (std::vector< std::pair< int, int >> &fields) const
	Describes the per-node memory layout of this IMP's state variables. More...

template<class Fn >
void	for_each_sv_field (node_index_t node, const std::vector< std::pair< int, int >> &fields, Fn &&fn)
	Visits each state-variable field of one node, in storage order. More...

size_t	get_sv_per_node_size () const
	Size in bytes of one node's de-interleaved state-variable record. More...

uint64_t	sv_fingerprint () const
	Fingerprint of this IMP's state-variable layout. More...

int	dump_luts (bool zipped)
	Dumps array of LUTs to file. More...

void	destroy_luts ()
	Destroys array of LUTs. More...

void	tune (const char im_par, const char plugs, const char *plug_par)
	Tunes specific IMP parameters from files. More...

int	read_svs (FILE *file)
	Reads state variable values for one cell from a file. More...

int	write_svs (FILE *file, node_index_t node)

virtual void	copy_SVs_from (IonIfBase &other, bool alloc)=0
	Copies the state variables of an IMP. More...

void	copy_plugins_from (IonIfBase &other)
	Copies the plugins of an IMP. More...

void	for_each (const std::function< void(IonIfBase &)> &consumer)
	Executes the `consumer` functions on this IMP and each of its plugins. More...

Public Attributes
int	miifIdx
	imp index within miif More...

Target	_target
	execution target for this IMP More...

Protected Attributes
ts	_tstp
	control time stepping More...

Detailed Description

Represents the ionic model and plug-in (IMP) data structure.

Definition at line 142 of file ION_IF.h.

Constructor & Destructor Documentation

◆ IonIfBase()

limpet::IonIfBase::IonIfBase	(	const IonType &	type,
		Target	target,
		node_count_t	num_node,
		const std::vector< std::reference_wrapper< IonType >> &	plugins
	)

Constructor for IonIfBase.

Parameters

type	ionic model type
target	this IMP will run on
num_node	number of cells handled by this IMP
plugins	array of plugin types (plugins attached to this IMP)

Definition at line 117 of file ION_IF.cc.

◆ ~IonIfBase()

limpet::IonIfBase::~IonIfBase ( )

virtual

Virtual destructor declaration.

Definition at line 134 of file ION_IF.cc.

Member Function Documentation

◆ cgeom()

cell_geom& limpet::IonIfBase::cgeom ( )

inline

Gets the cell geometry data.

Returns: the cell geometry data

Definition at line 261 of file ION_IF.h.

◆ compute()

void limpet::IonIfBase::compute	(	node_index_t	start,
		node_index_t	end,
		GlobalData_t **	data
	)

Perform ionic model computation for 1 time step.

Calls the compute functon if this IonIf's type with this IonIf's target.

Note: See limpet::IonType::compute

Definition at line 271 of file ION_IF.cc.

Here is the caller graph for this function:

◆ copy_plugins_from()

void limpet::IonIfBase::copy_plugins_from ( IonIfBase & other )

Copies the plugins of an IMP.

A new IonIf object is allocated for each plugin and the state variables are copies with a call to IonIf::copy_SVs_from.

Parameters

other IMP to copy the plugins from

Definition at line 506 of file ION_IF.cc.

◆ copy_SVs_from()

virtual void limpet::IonIfBase::copy_SVs_from	(	IonIfBase &	other,
		bool	alloc
	)

pure virtual

Copies the state variables of an IMP.

Parameters

other	where the values are copied from
alloc	true to allocate memory and copy IIF

Postcondition: the copy is only as deep as required for independent functioning of the copy and the original. Static data are shared.

Implemented in limpet::IonIf< T >.

Here is the caller graph for this function:

◆ destroy_luts()

void limpet::IonIfBase::destroy_luts ( )

Destroys array of LUTs.

Definition at line 440 of file ION_IF.cc.

◆ dump_luts()

int limpet::IonIfBase::dump_luts ( bool zipped )

Dumps array of LUTs to file.

Parameters

zipped	flag to toggle zipped output
return	number of LUTs dumped

Definition at line 421 of file ION_IF.cc.

◆ fill_buf()

char * limpet::IonIfBase::fill_buf	(	char *	buf,
		int *	n,
		opencarp::Salt_list *	l
	)		const

Appends the state variables to a buffer.

Parameters

buf	the buffer
n[inout]	current buffer size
l	list of local nodes to write

Note: buf is reallocated to hold new data

Returns: pointer to the increased buffer

Definition at line 275 of file ION_IF.cc.

◆ for_each()

void limpet::IonIfBase::for_each ( const std::function< void(IonIfBase &)> & consumer )

Executes the consumer functions on this IMP and each of its plugins.

Parameters

consumer functions to execute on each IMP

Definition at line 517 of file ION_IF.cc.

Here is the caller graph for this function:

◆ for_each_sv_field()

template<class Fn >

void limpet::IonIfBase::for_each_sv_field	(	node_index_t	node,
		const std::vector< std::pair< int, int >> &	fields,
		Fn &&	fn
	)

inline

Visits each state-variable field of one node, in storage order.

Resolves the data-layout-optimized address of local node node (block node/vec_size, lane nodevec_size, using THIS model's own dlo_vector_size() so a plugin is addressed with its own vector width) and invokes fn(field_ptr, field_size) for every field in fields. Shared by the checkpoint dump (gather) and restore (scatter) so the two cannot drift out of lockstep.

Parameters

node	local node index
fields	offset/size pairs from get_sv_layout
fn	callback invoked as fn(char* field_ptr, size_t field_size)

Definition at line 469 of file ION_IF.h.

Here is the caller graph for this function:

◆ get_dt()

float limpet::IonIfBase::get_dt ( ) const

Gets the basic integration time step.

Returns: the basic integration time step

Definition at line 201 of file ION_IF.cc.

◆ get_moddat()

uint32_t limpet::IonIfBase::get_moddat ( ) const

Gets the data flags for this IMP's modified data.

Returns: a bitmap containing the data flags

Definition at line 193 of file ION_IF.cc.

◆ get_n_tables_d()

size_t limpet::IonIfBase::get_n_tables_d ( ) const

Gets the size of the array returned by IonIf::tables_d.

Returns: the number of LUTs stored in the device-side LUT array (this number should be the same as IonIf::tables().size().

Definition at line 217 of file ION_IF.cc.

◆ get_num_node()

node_count_t limpet::IonIfBase::get_num_node ( ) const

Gets the number of nodes handled by this IMP.

Returns: the number of nodes

Definition at line 149 of file ION_IF.cc.

Here is the caller graph for this function:

◆ get_num_threads()

std::size_t limpet::IonIfBase::get_num_threads ( ) const

Gets the number of threads used for running this IMP.

Returns: the number of threads running this IMP (dependant on target)

Definition at line 153 of file ION_IF.cc.

Here is the caller graph for this function:

◆ get_reqdat()

uint32_t limpet::IonIfBase::get_reqdat ( ) const

Gets the data flags for this IMP's required data.

Returns: a bitmap containing the data flags

Definition at line 189 of file ION_IF.cc.

◆ get_sv_address()

virtual void* limpet::IonIfBase::get_sv_address ( )

pure virtual

Gets the raw address of the state variables for this IMP.

TODO: This is needed for now as many functions (write and read functions) and plugins (using the get_sv_offset function) still use the raw address of the SV table. This can be changed by rewriting the code that calls this function and by writing better tools that get_sv_offset for parent models.

Implemented in limpet::IonIf< T >.

Here is the caller graph for this function:

◆ get_sv_layout()

void limpet::IonIfBase::get_sv_layout ( std::vector< std::pair< int, int >> & fields ) const

Describes the per-node memory layout of this IMP's state variables.

Fills fields with one (byte offset, element size) pair per state variable, as reported by IonType::get_sv_offset. Under data-layout optimization the offset is the start of the variable's lane array within a block and the size is the size of a single lane (e.g. 4 for a float, regardless of vector width). Iterating these pairs and reading lane k of each field gathers one node's complete state.

Parameters

[out] fields offset/size pairs, one per state variable

Definition at line 342 of file ION_IF.cc.

Here is the caller graph for this function:

◆ get_sv_per_node_size()

size_t limpet::IonIfBase::get_sv_per_node_size ( ) const

Size in bytes of one node's de-interleaved state-variable record.

Sum of the per-lane field sizes from get_sv_layout (the model's own state only, excluding plugins). Equals get_sv_size() / dlo_vector_size() when the block holds no padding. This is the per-node record size used by the format >= 3 dump.

Definition at line 350 of file ION_IF.cc.

Here is the caller graph for this function:

◆ get_sv_size()

virtual std::size_t limpet::IonIfBase::get_sv_size ( ) const

pure virtual

Gets the size of the structure this IMP uses for state variables.

TODO: This is also needed for calling code to be able to use IonIfBase::get_sv_address as it returns a void pointer.

Implemented in limpet::IonIf< T >.

Here is the caller graph for this function:

◆ get_target()

Target limpet::IonIfBase::get_target ( ) const

inline

Definition at line 352 of file ION_IF.h.

Here is the caller graph for this function:

◆ get_tstp()

ts & limpet::IonIfBase::get_tstp ( )

Gets the time stepper.

Returns: the time stepper.

Definition at line 209 of file ION_IF.cc.

Here is the caller graph for this function:

◆ get_type()

const IonType & limpet::IonIfBase::get_type ( ) const

Gets this IMP's model type.

Returns: a reference to the IMP type (set of generated functions from model code).

Definition at line 145 of file ION_IF.cc.

Here is the caller graph for this function:

◆ initialize()

void limpet::IonIfBase::initialize	(	double	dt,
		GlobalData_t **	impdat
	)

virtual

Initializes lookup table and state variable tables.

Parameters

dt	time step
impdat	data

Precondition: numNode is set

Postcondition: lookup tables are allocated and filled
state variables are set to inital conditions

Todo:: {Further checks are needed: dt: (should be smaller than the max for each model) table range: Vm tables should be of the same size for all IIFs in use}

passing dt is no longer required

Reimplemented in limpet::IonIf< T >.

Definition at line 238 of file ION_IF.cc.

Here is the caller graph for this function:

◆ initialize_params()

void limpet::IonIfBase::initialize_params ( )

Initializes user modifiable parameters with default values defined in the respective ionic models.

Definition at line 230 of file ION_IF.cc.

◆ parent()

IonIfBase * limpet::IonIfBase::parent ( ) const

Gets the parent IMP.

Returns: a pointer to the parent of this IMP

Definition at line 177 of file ION_IF.cc.

Here is the caller graph for this function:

◆ plugins()

std::vector< IonIfBase * > & limpet::IonIfBase::plugins ( )

Returns a vector containing the plugins of this IMP.

Returns: a vector filled with plugins attached to this model

Definition at line 185 of file ION_IF.cc.

Here is the caller graph for this function:

◆ read_svs()

int limpet::IonIfBase::read_svs ( FILE * file )

Reads state variable values for one cell from a file.

Return values

0	good
1	temporary table allocated
>1	error

Definition at line 495 of file ION_IF.cc.

◆ restore()

node_count_t limpet::IonIfBase::restore	(	opencarp::FILE_SPEC	in,
		node_count_t	n,
		const node_index_t *	pos,
		IIF_Mask_t *	mask,
		size_t *	offset,
		IMPinfo *	impinfo,
		const global_node_index_t *	loc2canon
	)

Reads in the state variables for an IMP.

The data is verified to make sure it belongs to the expected type of IMP.

Parameters

in	output file
n	number of nodes
pos	partitioned node numbers
mask	global region mask ordered canonically
offset	file offset to SV info canonically ordered
impinfo	IMP information

Precondition: the SV tables are allocated

Postcondition: the SV tables have new values

Definition at line 288 of file ION_IF.cc.

◆ restore_per_node()

node_count_t limpet::IonIfBase::restore_per_node	(	opencarp::FILE_SPEC	in,
		node_count_t	n,
		const node_index_t *	pos,
		IIF_Mask_t *	mask,
		size_t *	offset,
		IMPinfo *	impinfo,
		const global_node_index_t *	loc2canon
	)

Reads in the state variables for an IMP from a per-node (format >= 3) dump.

Unlike IonIfBase::restore, which reads whole data-layout-optimized SoA blocks keyed by the block leader, this reads one contiguous, de-interleaved record per node keyed by the node's own canonical id and scatters each state-variable field back into its lane. This makes restore independent of the partitioning used to write the checkpoint. Generic in dlo_vector_size() (= 1 when DLO is disabled).

Parameters

in	input file
n	number of local nodes
pos	partitioned node numbers
mask	global region mask ordered canonically
offset	per-node file offsets, canonically ordered
impinfo	IMP information
loc2canon	local-to-canonical node map

Precondition: the SV tables are allocated

Postcondition: the SV tables have new values

Definition at line 373 of file ION_IF.cc.

◆ set_dt()

void limpet::IonIfBase::set_dt ( float dt )

Sets the basic integration time step.

Parameters

dt	the basic integration time step

Definition at line 205 of file ION_IF.cc.

◆ set_moddat()

void limpet::IonIfBase::set_moddat ( uint32_t data )

Set the data flag for this IMP's modified data.

Parameters

data	bitmap containing the data flags

Definition at line 197 of file ION_IF.cc.

◆ set_parent()

void limpet::IonIfBase::set_parent ( IonIfBase * parent )

Definition at line 181 of file ION_IF.cc.

◆ set_target()

void limpet::IonIfBase::set_target ( Target target )

virtual

Reimplemented in limpet::IonIf< T >.

Definition at line 221 of file ION_IF.cc.

Here is the caller graph for this function:

◆ sv_fingerprint()

uint64_t limpet::IonIfBase::sv_fingerprint ( ) const

Fingerprint of this IMP's state-variable layout.

A hash of the ordered (field name, per-lane size, type) tuples from get_sv_layout. It does not depend on the vector width or on byte offsets, so it is identical for DLO and non-DLO builds of the same model but changes if a state variable is renamed, retyped, or reordered. Stored in the format >= 3 dump header and checked on restore so a checkpoint written against a different model revision is skipped instead of silently misread field-for-field.

Definition at line 357 of file ION_IF.cc.

Here is the caller graph for this function:

◆ tables()

std::vector< LUT > & limpet::IonIfBase::tables ( )

Gets the array of state variables.

Returns: a reference to the state variable array structure.

Gets the lookup tables.

Returns: a reference to the vector of lookup tables (LUT) used by this IMP.

Definition at line 213 of file ION_IF.cc.

Here is the caller graph for this function:

◆ tables_d()

LUT* limpet::IonIfBase::tables_d ( ) const

inline

Gets an array of LUTs.

Returns: an array to LUT structures. Those LUTs are allocated on a device (GPU) and mirror the data in the vector returned by the IonIf::tables getter method.

Definition at line 337 of file ION_IF.h.

◆ tune()

void limpet::IonIfBase::tune	(	const char *	im_par,
		const char *	plugs,
		const char *	plug_par
	)

Tunes specific IMP parameters from files.

For each IMP, a comma separated list of expressions is specified. Each expression is of the form
parameter[+|-|=|/|*][-]###[.[###][e|E[-|+]###][%]
which specifies a float optionally preceded by * or + or - or / or = and optionally followed by a % (float is expressed as a percent of the default value). The meanings of the flags are

=: assign this value to the parameter
*: multiply the default parameter value by this
/: divide the default parameter value by this
+: add this to the default value
-: subtract this from the default value
%: treat the float as this percentage of the default

Plugins and their respective parameters must be specified in the same order

Parameters

im_par	comma separated list of IM specific parameters
plugs	plugins specified in colon separated list
plug_par	colon separated list of comma separated lists specifiying parameters for each plugin

Definition at line 448 of file ION_IF.cc.

◆ write_svs()

int limpet::IonIfBase::write_svs	(	FILE *	file,
		node_index_t	node
	)

Definition at line 502 of file ION_IF.cc.

Member Data Documentation

◆ _target

Target limpet::IonIfBase::_target

execution target for this IMP

Definition at line 155 of file ION_IF.h.

◆ _tstp

ts limpet::IonIfBase::_tstp

protected

control time stepping

Definition at line 157 of file ION_IF.h.

◆ miifIdx

int limpet::IonIfBase::miifIdx

imp index within miif

Definition at line 154 of file ION_IF.h.

The documentation for this class was generated from the following files:

physics/limpet/src/ION_IF.h
physics/limpet/src/ION_IF.cc

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ IonIfBase()

◆ ~IonIfBase()

Member Function Documentation

◆ cgeom()

◆ compute()

◆ copy_plugins_from()

◆ copy_SVs_from()

◆ destroy_luts()

◆ dump_luts()

◆ fill_buf()

◆ for_each()

◆ for_each_sv_field()

◆ get_dt()

◆ get_moddat()

◆ get_n_tables_d()

◆ get_num_node()

◆ get_num_threads()

◆ get_reqdat()

◆ get_sv_address()

◆ get_sv_layout()

◆ get_sv_per_node_size()

◆ get_sv_size()

◆ get_target()

◆ get_tstp()

◆ get_type()

◆ initialize()

◆ initialize_params()

◆ parent()

◆ plugins()

◆ read_svs()

◆ restore()

◆ restore_per_node()

◆ set_dt()

◆ set_moddat()

◆ set_parent()

◆ set_target()

◆ sv_fingerprint()

◆ tables()

◆ tables_d()

◆ tune()

◆ write_svs()

Member Data Documentation

◆ _target

◆ _tstp

◆ miifIdx