arts_api.h File Reference

#include "covariance_matrix.h"
#include "interactive_workspace.h"

Go to the source code of this file.

Classes
struct	VariableStruct
	Representation of ARTS WSVs. More...
struct	VariableValueStruct
	Representation of ARTS values. More...
struct	MethodStruct
	Representation of workspace methods. More...
struct	VersionStruct
	ARTS version. More...
struct	CovarianceMatrixBlockStruct
	Covariance matrix block. More...

Macros
#define	DLL_PUBLIC   __attribute__((visibility("default")))

Functions
DLL_PUBLIC void	include_path_push (const char *path)
	Add include path. More...
DLL_PUBLIC void	include_path_pop ()
	Remove last include path. More...
DLL_PUBLIC void	data_path_push (const char *path)
	Add data path. More...
DLL_PUBLIC void	data_path_pop ()
	Remove last data path. More...
DLL_PUBLIC void	initialize ()
	Initalize ARTS runtime. More...
DLL_PUBLIC void	finalize ()
	Finalize ARTS runtime. More...
DLL_PUBLIC const char *	get_error ()
	Get most recent error. More...
DLL_PUBLIC void	set_basename (const char *name)
	Set the ARTS basename. More...
DLL_PUBLIC Agenda *	parse_agenda (const char *filename)
	Parse Controlfile. More...
DLL_PUBLIC Agenda *	create_agenda (const char *name)
	Create Agenda. More...
DLL_PUBLIC void	agenda_add_method (Agenda *a, const Index id, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
	Add method to agenda. More...
DLL_PUBLIC void	agenda_insert_callback (Agenda *a, void(*f)(InteractiveWorkspace *))
	Insert callback into agenda. More...
DLL_PUBLIC void	agenda_insert_set (InteractiveWorkspace *ws, Agenda *a, long id, long group_id)
	Insert a set method into an agenda. More...
DLL_PUBLIC void	agenda_append (Agenda *dst, const Agenda *src)
	Append agendas. More...
DLL_PUBLIC void	agenda_clear (Agenda *a)
	Clear Agenda. More...
DLL_PUBLIC const char *	execute_agenda (InteractiveWorkspace *workspace, const Agenda *a)
	Execute Agenda. More...
DLL_PUBLIC void	destroy_agenda (Agenda *a)
	Destroy Agenda. More...
DLL_PUBLIC InteractiveWorkspace *	create_workspace (const Index verbosity=1, const Index agenda_verbosity=0)
	Create new workspace. More...
DLL_PUBLIC void	destroy_workspace (InteractiveWorkspace *workspace)
	Destroy given workspace. More...
DLL_PUBLIC unsigned long	get_number_of_groups ()
	Return number of WSV groups. More...
DLL_PUBLIC const char *	get_group_name (int i)
	Get pointer to name of given group. More...
DLL_PUBLIC unsigned long	get_number_of_methods ()
	Return number of WSMs. More...
DLL_PUBLIC MethodStruct	get_method (Index i)
	Return MethodStruct describing method with index i. More...
DLL_PUBLIC const char *	get_method_g_in (Index i, Index j)
	Get name of generic input argument. More...
DLL_PUBLIC const char *	get_method_g_in_default (Index i, Index j)
	Get default value of generic input argument. More...
DLL_PUBLIC const char *	get_g_in_nodef ()
	Get string defining missing default parameter. More...
DLL_PUBLIC const char *	get_method_g_out (Index i, Index j)
	Get name value of generic output argument. More...
DLL_PUBLIC const char *	execute_workspace_method (InteractiveWorkspace *workspace, long id, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
	Execute workspace method. More...
DLL_PUBLIC const char *	method_print_doc (long id)
	Print method documentation. More...
DLL_PUBLIC long	lookup_workspace_variable (const char *s)
	Lookup workspace variable by name. More...
DLL_PUBLIC unsigned long	get_number_of_variables ()
	Number of defined WSVs. More...
DLL_PUBLIC VariableStruct	get_variable (Index i)
	Get WSV by index. More...
DLL_PUBLIC VariableValueStruct	get_variable_value (InteractiveWorkspace *workspace, Index id, Index group_id)
	Get value WSV in given workspace. More...
DLL_PUBLIC void *	get_variable_data_pointer (InteractiveWorkspace *workspace, Index id)
	Get data pointer to the WSV variable. More...
DLL_PUBLIC CovarianceMatrixBlockStruct	get_covariance_matrix_block (CovarianceMatrix *m, long block_index, bool inverse)
	Return block of covariance matrix. More...
DLL_PUBLIC const char *	set_variable_value (InteractiveWorkspace *workspace, long id, long group_id, VariableValueStruct value)
	Sets the value of a WSV in a given workspace. More...
DLL_PUBLIC long	add_variable (InteractiveWorkspace *workspace, long group_id, const char *name)
	Add variable of given type to workspace. More...
DLL_PUBLIC void	erase_variable (InteractiveWorkspace *workspace, long id, long group_id)
	Erase variable from workspace. More...
DLL_PUBLIC VersionStruct	get_version ()
	Get ARTS Version. More...

Macro Definition Documentation

DLL_PUBLIC

#define DLL_PUBLIC   __attribute__((visibility("default")))

Definition at line 32 of file arts_api.h.

Referenced by add_variable(), erase_variable(), and get_g_in_nodef().

Function Documentation

add_variable()

DLL_PUBLIC long add_variable	(	InteractiveWorkspace *	workspace,
		long	group_id,
		const char *	name
	)

Add variable of given type to workspace.

This adds and initializes a variable in the current workspace and also adds a new entry to the global wsv_data array and updates WsvMap.

Parameters

workspace	The pointer to the InteractiveWorkspace object where to create the object.
group_id	The index of the group of the variable
name	Pointer to a null-terminated string containing the name of the variable. If nullptr, a name will be auto-generated.

Returns

The index which indentifies the variable in the given workspace.

Definition at line 637 of file arts_api.cc.

References InteractiveWorkspace::add_variable(), and DLL_PUBLIC.

Referenced by InteractiveWorkspace::add_callback(), and get_g_in_nodef().

agenda_add_method()

DLL_PUBLIC void agenda_add_method	(	Agenda *	a,
		const Index	id,
		unsigned long	n_args_out,
		const long *	args_out,
		unsigned long	n_args_in,
		const long *	args_in
	)

Add method to agenda.

Add a method to the given agenda.

Parameters

a	Pointer to agenda object.
id	Index of the method to add to the agenda.
n_args_out	Number of non-generic and generic output arguments.
args_out	Indices of the output variables.
n_args_in	Number of non-generic and generic input arguments.
args_in	Indices of the input variables.

agenda_append()

DLL_PUBLIC void agenda_append	(	Agenda *	dst,
		const Agenda *	src
	)

Append agendas.

Appends the methods in agenda src to agenda dst. This can be used to emulate include statements in agenda definitions.

Parameters

dst	The agenda to append the methods to
src	The agenda whose methods to append to src

Definition at line 171 of file arts_api.cc.

References Agenda::Methods(), methods(), and Agenda::push_back().

agenda_clear()

DLL_PUBLIC void agenda_clear

(

Agenda *

a

)

Clear Agenda.

Resets a given agenda to be emtpy.

Parameters

a	Pointer to agenda object.

Definition at line 178 of file arts_api.cc.

agenda_insert_callback()

DLL_PUBLIC void agenda_insert_callback	(	Agenda *	a,
		void(*)(InteractiveWorkspace *)	f
	)

Insert callback into agenda.

Inserts callback to the given function object into the agenda.

Definition at line 149 of file arts_api.cc.

References InteractiveWorkspace::add_callback(), global_data::md_data, and Agenda::push_back().

agenda_insert_set()

DLL_PUBLIC void agenda_insert_set	(	InteractiveWorkspace *	ws,
		Agenda *	a,
		long	id,
		long	group_id
	)

Insert a set method into an agenda.

This inserts a set method into the given agenda which sets the a workspace variable given by its ID to to the value it currently has in the given workspace.

Parameters

Pointer	to the workspace
Pointer	to the agenda
Pointer	to the callback function object
Language	type of the callback.

Definition at line 94 of file arts_api.cc.

References global_data::MdMap, Agenda::push_back(), and global_data::wsv_group_names.

create_agenda()

DLL_PUBLIC Agenda* create_agenda

(

const char *

name

)

Create Agenda.

Creates an empyt agenda.

Parameters

[in]

name

Name of the agenda

Returns

Pointer to the newly created agenda.

Definition at line 88 of file arts_api.cc.

References Agenda::set_name().

create_workspace()

DLL_PUBLIC InteractiveWorkspace* create_workspace	(	const Index	verbosity = 1,
		const Index	agenda_verbosity = 0
	)

Create new workspace.

Returns

Pointer to a newly created InteractiveWorkspace object.

Definition at line 191 of file arts_api.cc.

data_path_pop()

DLL_PUBLIC void data_path_pop

(

)

Remove last data path.

Remove the most recently added data path. Will result in an exception if the data path is empty.

Definition at line 58 of file arts_api.cc.

References Parameters::datapath.

data_path_push()

DLL_PUBLIC void data_path_push

(

const char *

path

)

Add data path.

Adds a given path to the ARTS data path.

Parameters

[in]

path

Pointer to cstring containing the path to add to the data path.

Definition at line 56 of file arts_api.cc.

References Parameters::datapath.

destroy_agenda()

DLL_PUBLIC void destroy_agenda

(

Agenda *

a

)

Destroy Agenda.

Parameters

a	Pointer to the agenda.

Definition at line 186 of file arts_api.cc.

destroy_workspace()

DLL_PUBLIC void destroy_workspace

(

InteractiveWorkspace *

workspace

)

Destroy given workspace.

Definition at line 196 of file arts_api.cc.

erase_variable()

DLL_PUBLIC void erase_variable	(	InteractiveWorkspace *	workspace,
		long	id,
		long	group_id
	)

Erase variable from workspace.

This variable removes a variable from the workspace and the global wsv_data and WsvMap. This is likely to invalidate indices of existing variables so it should be used with care.

Parameters

workspace	Pointer to the InteractiveWorkspace object owning the variable
id	The index of the variable
group_id	The index of the group of the variable

Definition at line 644 of file arts_api.cc.

References DLL_PUBLIC, and InteractiveWorkspace::erase_variable().

Referenced by InteractiveWorkspace::add_callback(), and get_g_in_nodef().

execute_agenda()

DLL_PUBLIC const char* execute_agenda	(	InteractiveWorkspace *	workspace,
		const Agenda *	a
	)

Execute Agenda.

Executes the given agenda on a given workspace.

Parameters

workspace	Pointer of the InteractiveWorkspace object to execute the agenda on.
a	Pointer to the agenda to execute.

Returns

NULL if execution was successfull, otherwise pointer to the c_str holding the error message from ARTS.

Definition at line 180 of file arts_api.cc.

References InteractiveWorkspace::execute_agenda(), and Agenda::set_main_agenda().

execute_workspace_method()

DLL_PUBLIC const char* execute_workspace_method	(	InteractiveWorkspace *	workspace,
		long	id,
		unsigned long	n_args_out,
		const long *	args_out,
		unsigned long	n_args_in,
		const long *	args_in
	)

Execute workspace method.

Execute workspace method with given index. Input arguments are passed using pointers to two arrays holding the indices of the input arguments and the output arguments, respectively. The length of the input (output) arguments must of course match the number of non-generic and generic input (output) arguments.

Parameters

i	The index of the WSM
args_out	Pointer to the array holding the indices of the output WSVs.
args_in	Pointer to the array holding the indices of the input WSVs.

Returns

NULL if execution of workspace method was successful, pointer to c_str hodling the ARTS error message otherwise.

Definition at line 262 of file arts_api.cc.

References copy_output_and_input(), and InteractiveWorkspace::execute_workspace_method().

Referenced by get_g_in_nodef().

finalize()

DLL_PUBLIC void finalize

(

)

Finalize ARTS runtime.

Deletes the error buffer.

Definition at line 62 of file arts_api.cc.

get_covariance_matrix_block()

DLL_PUBLIC CovarianceMatrixBlockStruct get_covariance_matrix_block	(	CovarianceMatrix *	m,
		long	block_index,
		bool	inverse
	)

Return block of covariance matrix.

Parameters

m	Pointer to covariance matrix from which to return the block.
block_index	Index of the block to return.
inverse	Whether the block should be returned from the list of inverse blocks or not.

Returns

Returns the block identified by the given pointer represented by CovarianceMatrixBlockStruct.

Definition at line 467 of file arts_api.cc.

References Block::dense, CovarianceMatrix::get_blocks(), MatrixView::get_c_array(), Sparse::get_column_index_pointer(), Block::get_column_range(), Block::get_dense(), Sparse::get_element_pointer(), Range::get_extent(), Block::get_indices(), CovarianceMatrix::get_inverse_blocks(), Block::get_matrix_type(), Block::get_row_range(), Sparse::get_row_start_pointer(), Block::get_sparse(), Range::get_start(), i, CovarianceMatrixBlockStruct::indices, and Sparse::nnz().

Referenced by get_g_in_nodef().

get_error()

DLL_PUBLIC const char* get_error

(

)

Get most recent error.

Returns

Pointer to the c string holding the most recent error message.

Definition at line 66 of file arts_api.cc.

References string_buffer.

get_g_in_nodef()

DLL_PUBLIC const char* get_g_in_nodef

(

)

Get string defining missing default parameter.

Definition at line 468 of file arts_api.h.

References add_variable(), DLL_PUBLIC, erase_variable(), execute_workspace_method(), get_covariance_matrix_block(), get_method_g_out(), get_number_of_variables(), get_variable(), get_variable_data_pointer(), get_variable_value(), get_version(), i, lookup_workspace_variable(), method_print_doc(), VariableStruct::name, NODEF, and set_variable_value().

get_group_name()

DLL_PUBLIC const char* get_group_name

(

int

i

)

Get pointer to name of given group.

Definition at line 204 of file arts_api.cc.

References i, and global_data::wsv_group_names.

get_method()

DLL_PUBLIC MethodStruct get_method

(

Index

i

)

Return MethodStruct describing method with index i.

Definition at line 211 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_in()

DLL_PUBLIC const char* get_method_g_in	(	Index	i,
		Index	j
	)

Get name of generic input argument.

Parameters

[in]	i	The index of the WSM
[in]	The	index of the generic input arguments

Returns

Pointer to c_str holding the name of the input argument as defined in methods.cc.

Definition at line 246 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_in_default()

DLL_PUBLIC const char* get_method_g_in_default	(	Index	i,
		Index	j
	)

Get default value of generic input argument.

Parameters

[in]	i	The index of the WSM
[in]	j	The index of the generic input argument

Returns

Pointer to c_str holding the default value as defined in methods.cc.

Definition at line 250 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_out()

DLL_PUBLIC const char* get_method_g_out	(	Index	i,
		Index	j
	)

Get name value of generic output argument.

Parameters

[in]	i	The index of the WSM
[in]	j	The index of the generic output argument

Returns

Pointer to c_str holding the name of the output argument as defined in methods.cc.

Definition at line 258 of file arts_api.cc.

References i, and global_data::md_data.

Referenced by get_g_in_nodef().

get_number_of_groups()

DLL_PUBLIC unsigned long get_number_of_groups

(

)

Return number of WSV groups.

Definition at line 202 of file arts_api.cc.

References global_data::wsv_group_names.

get_number_of_methods()

DLL_PUBLIC unsigned long get_number_of_methods

(

)

Return number of WSMs.

Definition at line 209 of file arts_api.cc.

References global_data::md_data.

get_number_of_variables()

DLL_PUBLIC unsigned long get_number_of_variables

(

)

Number of defined WSVs.

Definition at line 293 of file arts_api.cc.

References Workspace::wsv_data.

Referenced by get_g_in_nodef().

get_variable()

DLL_PUBLIC VariableStruct get_variable

(

Index

i

)

Get WSV by index.

Parameters

The	index of the WSV

Returns

VariableStruct representing the WSV

Definition at line 295 of file arts_api.cc.

References WsvRecord::Description(), WsvRecord::Group(), i, WsvRecord::Name(), r, and Workspace::wsv_data.

Referenced by get_g_in_nodef().

get_variable_data_pointer()

DLL_PUBLIC void* get_variable_data_pointer	(	InteractiveWorkspace *	workspace,
		Index	id
	)

Get data pointer to the WSV variable.

Initalize uninitialized WSV variable

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.

Returns

void * to the data

Definition at line 463 of file arts_api.cc.

Referenced by get_g_in_nodef().

get_variable_value()

DLL_PUBLIC VariableValueStruct get_variable_value	(	InteractiveWorkspace *	workspace,
		Index	id,
		Index	group_id
	)

Get value WSV in given workspace.

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.
group_id	Index of the group the variable belongs to.

Returns

VariableValueStruct providing access to the variable.

Definition at line 300 of file arts_api.cc.

References ConstTensor3View::empty(), ConstTensor4View::empty(), ConstTensor5View::empty(), ConstTensor7View::empty(), ConstTensor6View::empty(), ConstVectorView::empty(), ConstMatrixView::empty(), Tensor3View::get_c_array(), Tensor4View::get_c_array(), Tensor5View::get_c_array(), VectorView::get_c_array(), Tensor6View::get_c_array(), MatrixView::get_c_array(), Tensor7View::get_c_array(), Sparse::get_column_index_pointer(), Sparse::get_element_pointer(), Sparse::get_row_start_pointer(), Workspace::is_initialized(), ConstTensor4View::nbooks(), ConstTensor5View::nbooks(), ConstTensor7View::nbooks(), ConstTensor6View::nbooks(), Sparse::ncols(), ConstTensor4View::ncols(), ConstTensor3View::ncols(), ConstTensor5View::ncols(), ConstTensor7View::ncols(), ConstTensor6View::ncols(), ConstMatrixView::ncols(), ConstVectorView::nelem(), ConstTensor7View::nlibraries(), Sparse::nnz(), ConstTensor3View::npages(), ConstTensor4View::npages(), ConstTensor5View::npages(), ConstTensor7View::npages(), ConstTensor6View::npages(), Sparse::nrows(), ConstTensor4View::nrows(), ConstTensor3View::nrows(), ConstTensor5View::nrows(), ConstTensor7View::nrows(), ConstTensor6View::nrows(), ConstMatrixView::nrows(), ConstTensor5View::nshelves(), ConstTensor7View::nshelves(), ConstTensor6View::nshelves(), ConstTensor7View::nvitrines(), ConstTensor6View::nvitrines(), and global_data::wsv_group_names.

Referenced by get_g_in_nodef().

get_version()

DLL_PUBLIC VersionStruct get_version

(

)

Get ARTS Version.

This function returns the ARTS version number as a double precision floating point number.

Returns

The ARTS version.

Definition at line 649 of file arts_api.cc.

References ARTS_FULL_VERSION, VersionStruct::major, VersionStruct::minor, and VersionStruct::revision.

Referenced by get_g_in_nodef().

include_path_pop()

DLL_PUBLIC void include_path_pop

(

)

Remove last include path.

Remove the most recently added include path. Will result in an exception if the include path is empty.

Definition at line 54 of file arts_api.cc.

References Parameters::includepath.

include_path_push()

DLL_PUBLIC void include_path_push

(

const char *

path

)

Add include path.

Pushes a given path to the back of the include path.

Parameters

[in]

path

Pointer to cstring containing the path to add to the include path.

Definition at line 50 of file arts_api.cc.

References Parameters::includepath.

initialize()

DLL_PUBLIC void initialize

(

)

Initalize ARTS runtime.

This function must be called before any other function to initialize the ARTS C API otherwise bad things will probably happen.

Definition at line 60 of file arts_api.cc.

References InteractiveWorkspace::initialize().

lookup_workspace_variable()

DLL_PUBLIC long lookup_workspace_variable

(

const char *

s

)

Lookup workspace variable by name.

Parameters

s	Pointer to c string holding the name of the variable.

Returns

Index of the variable or -1 if no variable with the given name exists.

Definition at line 285 of file arts_api.cc.

References Zeeman::end(), and Workspace::WsvMap.

Referenced by get_g_in_nodef().

method_print_doc()

DLL_PUBLIC const char* method_print_doc

(

long

id

)

Print method documentation.

This prints the documentation of the method as it is found for example in the HTML browser to the stream buffer and returns a pointer to it.

Parameters

id	The id of the method.

Returns

Pointer to c string holding the documentation of the method

Definition at line 274 of file arts_api.cc.

References global_data::md_data, and string_buffer.

Referenced by get_g_in_nodef().

parse_agenda()

DLL_PUBLIC Agenda* parse_agenda

(

const char *

filename

)

Parse Controlfile.

Parses a controlfile into an Agenda and returns a handle to to this agenda, which can be executed on a workspace using execute_agenda(...).

Note that parsing the same controlfile twice fails if this controlfile creates new WSVs.

Parameters

Definition at line 73 of file arts_api.cc.

References ArtsParser::parse_tasklist(), Agenda::set_main_agenda(), and Agenda::set_name().

set_basename()

DLL_PUBLIC void set_basename

(

const char *

name

)

Set the ARTS basename.

The basename is a global variable that is used in some cases by some WSMs for example to store or read data.

Definition at line 68 of file arts_api.cc.

set_variable_value()

DLL_PUBLIC const char* set_variable_value	(	InteractiveWorkspace *	workspace,
		long	id,
		long	group_id,
		VariableValueStruct	value
	)

Sets the value of a WSV in a given workspace.

This method can be used to set the value of an ARTS WSV from external data. Currently supported data types are:

• Agenda
• ArrayOfIndex
• ArrayOfString
• Index
• Matrix
• Numeric
• Sparse
• String
• Tensor3, ..., Tensor7
• Vector

For Index and Numeric the data pointer of the VariableValueStruct is assumed to point to the value to set the WSV to. For variables of type String the data pointer is interpreted as pointer to a c_str. For ArrayOfString the data pointer is assumed to point to an array of pointers to c_str. For Vectors and Matrix data is assumed to point an array of double with c-style memory layout and size given by the corresponding values in the dimension field of VariableValueStruct.

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.
group_id	Index of the group the variable belongs to.

Returns

Poiter to null-terminated string containing the error message if setting of variable fails.

Definition at line 512 of file arts_api.cc.

References InteractiveWorkspace::initialize_variable(), VariableValueStruct::ptr, InteractiveWorkspace::set_agenda_variable(), and global_data::wsv_group_names.

Referenced by get_g_in_nodef().