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...

virtual void	initialize_state (double dt, GlobalData_t **impdat)
	Initializes state and private workspace without constructing LUTs. 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 ()
	Releases this IMP's lookup-table handle. More...

void	rebuild_lookup_tables ()
	Rebuilds this IMP's lookup tables and GPU definition mirror. More...

void	share_lookup_tables_from (const IonIfBase &other)
	Shares an initialized lookup-table set with an equivalent IMP. 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...

virtual void	copy_configuration_from (IonIfBase &other)=0
	Copies model configuration needed to initialize an equivalent 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 Member Functions
bool	has_lookup_tables () const

Protected Attributes
ts	_tstp
	control time stepping More...

Detailed Description

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

Definition at line 168 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 109 of file ION_IF.cc.

◆ ~IonIfBase()

limpet::IonIfBase::~IonIfBase ( )

virtual

Virtual destructor declaration.

Definition at line 126 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 290 of file ION_IF.h.

Here is the caller graph for this function:

◆ 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 258 of file ION_IF.cc.

Here is the caller graph for this function:

◆ copy_configuration_from()

virtual void limpet::IonIfBase::copy_configuration_from ( IonIfBase & other )

pure virtual

Copies model configuration needed to initialize an equivalent IMP.

State variables, private workspace, lookup tables, targets, and external data mappings are not copied.

Parameters

other IMP to copy typed parameters and cell geometry from

Implemented in limpet::IonIf< T >.

◆ 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 515 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 ( )

Releases this IMP's lookup-table handle.

Shared storage remains alive until the last source or doppel releases it.

Definition at line 425 of file ION_IF.cc.

Here is the caller graph for this function:

◆ 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 402 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 262 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 526 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 505 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 190 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 182 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 208 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 138 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 142 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 178 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 326 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 334 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 381 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 198 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 134 of file ION_IF.cc.

Here is the caller graph for this function:

◆ has_lookup_tables()

bool limpet::IonIfBase::has_lookup_tables ( ) const

inlineprotected

Definition at line 204 of file ION_IF.h.

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 232 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 224 of file ION_IF.cc.

◆ initialize_state()

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

virtual

Initializes state and private workspace without constructing LUTs.

Used by doppels after they share their source IMP's immutable LUT set.

Reimplemented in limpet::IonIf< T >.

Definition at line 249 of file ION_IF.cc.

Here is the caller graph for this function:

◆ parent()

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

Gets the parent IMP.

Returns: a pointer to the parent of this IMP

Definition at line 166 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 174 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 504 of file ION_IF.cc.

◆ rebuild_lookup_tables()

void limpet::IonIfBase::rebuild_lookup_tables ( )

Rebuilds this IMP's lookup tables and GPU definition mirror.

The integration time step and model parameters must already be current.

Definition at line 432 of file ION_IF.cc.

Here is the caller graph for this function:

◆ 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 275 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 357 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 194 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 186 of file ION_IF.cc.

◆ set_parent()

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

Definition at line 170 of file ION_IF.cc.

Here is the caller graph for this function:

◆ set_target()

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

virtual

Reimplemented in limpet::IonIf< T >.

Definition at line 212 of file ION_IF.cc.

Here is the caller graph for this function:

◆ share_lookup_tables_from()

void limpet::IonIfBase::share_lookup_tables_from ( const IonIfBase & other )

Shares an initialized lookup-table set with an equivalent IMP.

Both IMPs must have the same model type and execution target.

Definition at line 449 of file ION_IF.cc.

◆ 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 341 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 202 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 366 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 457 of file ION_IF.cc.

◆ write_svs()

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

Definition at line 511 of file ION_IF.cc.

Member Data Documentation

◆ _target

Target limpet::IonIfBase::_target

execution target for this IMP

Definition at line 181 of file ION_IF.h.

◆ _tstp

ts limpet::IonIfBase::_tstp

protected

control time stepping

Definition at line 183 of file ION_IF.h.

◆ miifIdx

int limpet::IonIfBase::miifIdx

imp index within miif

Definition at line 180 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 Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ IonIfBase()

◆ ~IonIfBase()

Member Function Documentation

◆ cgeom()

◆ compute()

◆ copy_configuration_from()

◆ 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()

◆ has_lookup_tables()

◆ initialize()

◆ initialize_params()

◆ initialize_state()

◆ parent()

◆ plugins()

◆ read_svs()

◆ rebuild_lookup_tables()

◆ restore()

◆ restore_per_node()

◆ set_dt()

◆ set_moddat()

◆ set_parent()

◆ set_target()

◆ share_lookup_tables_from()

◆ sv_fingerprint()

◆ tables()

◆ tables_d()

◆ tune()

◆ write_svs()

Member Data Documentation

◆ _target

◆ _tstp

◆ miifIdx