API for use by applications using libkissinference . More...

Data Structures
struct	kiss_vector
	A struct containing a named vector. More...

struct	kiss_network
	Struct describing a kiss neural network. More...

struct	kiss_training_session
	Struct describing a training session. More...

struct	kiss_data_feed_cb_t
	A function pointer of this type is used by libkissinference-train to request data from the user. More...

Typedefs
typedef void(*	kiss_data_free_cb_t) (struct kiss_training_data data, void usr_ptr)
	A function pointer of this type is used by libkissinference to free data requested by the user of this libary via a kiss_data_feed_cb_t callback.

typedef void(*	kiss_train_progress_cb_t) (struct kiss_training_session session, kiss_train_state_t state, float loss, int step, void usr_ptr)
	A function pointer of this type is used by libkissinference to inform the user of this libary.

Enumerations
enum	kiss_loss_t { KISS_LOSS_NNL }

enum	kiss_train_state_t { KISS_STEP_COMPLETED , KISS_COMPLETED , KISS_ERROR_STATE }

Functions
void	kiss_free_network (struct kiss_network *net)
	Frees the resources associated with a network.

void	kiss_free_network_prealloc (struct kiss_network *net)
	Same as kiss_free_network except it dose not free the network struct itself.

struct kiss_network *	kiss_load_network (const char path, void(result_cb)(float result, struct kiss_network net, void *user_data), bool verbose)
	Loads a network from disk.

struct kiss_vector *	kiss_create_vector (const char name, float values, size_t length)
	Allocate a vector struct of length elements and copy the given data into the vector.

void	kiss_free_vector (struct kiss_vector *vector)
	Frees the given vector.

bool	kiss_load_network_prealloc (struct kiss_network net, const char path, void(result_cb)(float result, struct kiss_network net, void user_data), bool verbose)
	Loads a network from disk.

struct kiss_network *	kiss_load_network_from_buffer (const char buffer, size_t size, void(result_cb)(float result, struct kiss_network net, void *user_data), bool verbose)
	Loads a network from a memory address.

bool	kiss_load_network_from_buffer_prealloc (struct kiss_network net, const char buffer, size_t size, void(result_cb)(float result, struct kiss_network net, void user_data), bool verbose)
	Loads a network from a memory address.

bool	kiss_async_run_inference (struct kiss_network net, const struct kiss_vector inputs, size_t inputs_count, void *user_data)
	Runs inference on a network with the given inputs.

bool	kiss_set_output_mask (struct kiss_network net, const bool output_mask)
	Sets the output mask on a given network.

size_t	kiss_get_active_output_count (struct kiss_network *net)
	Gets the number of outputs not masked by the input mask.

float *	kiss_create_range (float start, float end, size_t length, bool log)
	Allocates an array of floats that contins a linear or log range.

void	kiss_resample_spectra (float in_re, float in_im, size_t input_length, float out_re, float out_im, size_t output_length)
	Resamples a spectra, useing linear interpolation.

void	kiss_normalize_spectra (float in_re, float in_im, size_t input_length)
	Normalizes the given spectra to [0,1].

bool	kiss_reduce_spectra (float in_re, float in_im, float omegas, size_t input_length, float thresh_factor, bool use_second_deriv, float out_re, float out_im, size_t output_length)
	Reduces the data by removing "uninteresting" regions.

bool	kiss_filter_spectra (float in_re, float in_im, float omegas, size_t input_length, float out_re, float *out_im, size_t output_length)
	Filteres the spectra by applying kiss_normalize_spectra, kiss_reduce_spectra and kiss_resample_spectra.

float *	kiss_absgrad (float in_re, float in_im, float *omegas, size_t input_length, size_t index)
	Calculates the element wise absolute gradient at the given point of the data given.

float	kiss_grad (float data, float omegas, size_t input_length, size_t index)
	Approximates the gradiant at the given index.

float	kiss_median (float *data, size_t input_length)
	Calculates the median of the given data.

float	kiss_mean (float *data, size_t input_length)
	Calculates the mean of the given data.

const char *	kiss_get_strerror (struct kiss_network *net)
	Normalizes the given spectra to [0,1].

void	kiss_softmax (float *data, size_t input_length)
	Applies softmax to the given data.

void	kiss_linear (float data, float weight, float *bias, size_t lengh)
	Applies a linear nn layer to the given input.

void	kiss_softmax_masked (float data, bool mask, size_t input_length)
	Applies softmax to the given data ignoreing the inputs where mask is false.

bool	kiss_float_eq (float a, float b, unsigned int ulp)
	Checks the given floats for equality with a tollerance of ulp epsilons around the sum of the inputs.

char *	kiss_eis_to_relaxis (const char *in)
	Translates a string for this library to the format used by RHD instruments RelaxIS.

char *	kiss_eis_to_cdc (const char *in)
	Translates a string for this library a Boukamp Circuit Description Code (CDC).

void	kiss_free (void *data)
	Frees the data with the same allocateor as libkissinference.

struct kiss_training_session *	kiss_create_training_session (const char *path, int batch_size)
	Loads a training session archive from disk.

bool	kiss_create_training_session_prealloc (struct kiss_training_session session, const char path, int batch_size)
	Loads a training session archive from disk while using a session allocated by the caller.

void	kiss_free_training_session (struct kiss_training_session *session)
	Frees a kiss_training_session.

void	kiss_free_training_session_prealloc (struct kiss_training_session *session)
	Frees the resources associated with a kiss_training_session but not the struct itself.

bool	kiss_start_training (struct kiss_training_session session, kiss_loss_t loss, kiss_data_feed_cb_t datafeeder, kiss_data_free_cb_t datafreeer, kiss_train_progress_cb_t progresscb, void user_ptr)
	Starts training the network.

void	kiss_finish_training (struct kiss_training_session *session)
	Finalizes training of the network.

const char *	kiss_train_get_strerror (struct kiss_training_session *session)
	Gets a error description string descrebing the lass orccured error.

const char *	kiss_state_to_str (kiss_train_state_t state)
	Gets a description string descrebing the state.

Detailed Description

API for use by applications using libkissinference .

API for use by applications using libkissinference-train .

Api to use kiss models

Api to finetune kiss models

Typedef Documentation

◆ kiss_data_free_cb_t

typedef void(* kiss_data_free_cb_t) (struct kiss_training_data *data, void *usr_ptr)

A function pointer of this type is used by libkissinference to free data requested by the user of this libary via a kiss_data_feed_cb_t callback.

Parameters

data	the data to be freed
user_ptr	the user pointer supplied to kiss_start_training

◆ kiss_train_progress_cb_t

typedef void(* kiss_train_progress_cb_t) (struct kiss_training_session *session, kiss_train_state_t state, float loss, int step, void *usr_ptr)

A function pointer of this type is used by libkissinference to inform the user of this libary.

Parameters

data	the data to be freed
user_ptr	the user pointer supplied to kiss_start_training

Enumeration Type Documentation

◆ kiss_train_state_t

enum kiss_train_state_t

Enumerator
KISS_STEP_COMPLETED	Emmited when a training optimizer step compleates, not emmited after the final step.
KISS_COMPLETED	Emmited when a training completes the final optimizer step.
KISS_ERROR_STATE	Emmited when an error is encountered.

Function Documentation

◆ kiss_absgrad()

float * kiss_absgrad	(	float *	in_re,
		float *	in_im,
		float *	omegas,
		size_t	input_length,
		size_t	index )

Calculates the element wise absolute gradient at the given point of the data given.

Parameters

in_re	The real part of the input spectra.
in_im	The imaginary part of the input spectra.
in_im	The frequencies of the input spectra.
input_length	The length of the input spectra.
index	The index at which to aproxmiate the gradiant

◆ kiss_async_run_inference()

bool kiss_async_run_inference	(	struct kiss_network *	net,
		const struct kiss_vector *	inputs,
		size_t	inputs_count,
		void *	user_data )

Runs inference on a network with the given inputs.

The inputs parameter is copied and may be freed immidatly after the call to this function. net must remain valid until the corrisponding result_cb call is recived.

Parameters

inputs	An array of floats, must as long as input_size for the network.
user_data	A pointer that will be passed to the callback

Returns: true if the inference call was sucessfully dispatched, will return false and set an error for kiss_get_strerror() otherwise.

◆ kiss_create_range()

float * kiss_create_range	(	float	start,
		float	end,
		size_t	length,
		bool	log )

Allocates an array of floats that contins a linear or log range.

Parameters

start	The start of the range.
end	The end of the range.
length	The amount of elements in the range.
log	If true the points in the range will be distrobuted in along a log10 spaceing, otherwise linear spaceing will be used.

Returns: A newly allocated array of floats, to be freed with free().

◆ kiss_create_training_session()

struct kiss_training_session * kiss_create_training_session	(	const char *	path,
		int	batch_size )

Loads a training session archive from disk.

If allocation fails this function will return NULL, for all other errors this function will return a network with ready set to false. In this case a detailed error string can be aquired by calling kiss_train_get_strerror on the network. Any result, except NULL, of this function musst be freed with kiss_free_training_session().

To avoid leaking memory, the result parameter of result_cb must be freed by result_cb or subsiquently managed by the user of this api.

Parameters

path	A path to a training archive.
batch_size	the batch size for training

Returns: a pointer to a newly allocated struct kiss_training_session to be freed with kiss_free_training_session() or NULL on allocation failure.

◆ kiss_create_training_session_prealloc()

bool kiss_create_training_session_prealloc	(	struct kiss_training_session *	session,
		const char *	path,
		int	batch_size )

Loads a training session archive from disk while using a session allocated by the caller.

In case of an error this function will set return false and the ready bit in the network to false. In this case a detailed error string can be aquired by calling kiss_train_get_strerror. The resources associated with the session created by this function musst be freed with kiss_free_training_session_prealloc(). The session struct itself must be freed by the caller of this function after calling kiss_free_training_session_prealloc.

Parameters

session	A prellocated kiss_training_session struct
path	A path to a training archive.
batch_size	the batch size for training.

Returns: true on sucess, false on failure.

◆ kiss_create_vector()

struct kiss_vector * kiss_create_vector	(	const char *	name,
		float *	values,
		size_t	length )

Allocate a vector struct of length elements and copy the given data into the vector.

Parameters

name	A label describing the vector
values	The values to be copied into the vector

Returns: a pointer to a newly allocated kiss_vector struct to be freed by kiss_free_vector or NULL on OOM

◆ kiss_eis_to_cdc()

char * kiss_eis_to_cdc ( const char * in )

Translates a string for this library a Boukamp Circuit Description Code (CDC).

Note that any parameters embedded into the eisgenerator model string will be striped and not included in the CDC.

Parameters

in	The eisgenerator model string.

Returns: A newly allocated CDC string. To be freed with free() or NULL if translation failed

◆ kiss_eis_to_relaxis()

char * kiss_eis_to_relaxis ( const char * in )

Translates a string for this library to the format used by RHD instruments RelaxIS.

Note that any parameters embedded into the eisgenerator model string will be striped and not included in the RelaxIS model.

Parameters

in	The eisgenerator model string.

Returns: A newly allocated RelaxIS model string. To be freed with free() or NULL if translation failed

◆ kiss_filter_spectra()

bool kiss_filter_spectra	(	float *	in_re,
		float *	in_im,
		float *	omegas,
		size_t	input_length,
		float **	out_re,
		float **	out_im,
		size_t	output_length )

Filteres the spectra by applying kiss_normalize_spectra, kiss_reduce_spectra and kiss_resample_spectra.

Parameters

in_re	The real part of the input spectra.
in_im	The imaginary part of the input spectra.
input_length	The length of the input spectra.
out_re	A pointer where the real part of the filtered spectra will be allocated. to be freed with free().
out_im	A pointer where the imaginary part of the filtered spectra will be allocated. to be freed with free().
output_length	The length the spectra needs to have for the network.
return	returns true if the spectra was filtered sucessfully, false otherwise, dose not set kiss_get_strerror

◆ kiss_finish_training()

void kiss_finish_training ( struct kiss_training_session * session )

Finalizes training of the network.

this function must be called after KISS_COMPLETED is set to the associated kiss_train_progress_cb_t.

Parameters

session The session to be finalized.

◆ kiss_float_eq()

bool kiss_float_eq	(	float	a,
		float	b,
		unsigned int	ulp )

Checks the given floats for equality with a tollerance of ulp epsilons around the sum of the inputs.

Parameters

a	The first input.
b	The second input to be compared with the first.
ulp	number of epsilons of tollerance.

Returns: True if the value of b is within ulp epsilons of a, false otherwise.

◆ kiss_free()

void kiss_free ( void * data )

Frees the data with the same allocateor as libkissinference.

Parameters

data	A pointer to the data to free

◆ kiss_free_network()

void kiss_free_network ( struct kiss_network * net )

Frees the resources associated with a network.

Parameters

net	The network to free.

◆ kiss_free_network_prealloc()

void kiss_free_network_prealloc ( struct kiss_network * net )

Same as kiss_free_network except it dose not free the network struct itself.

Parameters

net	The network to free.

◆ kiss_free_training_session()

void kiss_free_training_session ( struct kiss_training_session * session )

Frees a kiss_training_session.

Parameters

session The session to be freed.

◆ kiss_free_training_session_prealloc()

void kiss_free_training_session_prealloc ( struct kiss_training_session * session )

Frees the resources associated with a kiss_training_session but not the struct itself.

Parameters

session The session whos resources shal be freed.

◆ kiss_free_vector()

void kiss_free_vector ( struct kiss_vector * vector )

Frees the given vector.

Parameters

vector the vector to be freed

◆ kiss_get_active_output_count()

size_t kiss_get_active_output_count ( struct kiss_network * net )

Gets the number of outputs not masked by the input mask.

Parameters

net	The network to get the active count for

Returns: the number of active outputs

◆ kiss_get_strerror()

const char * kiss_get_strerror ( struct kiss_network * net )

Normalizes the given spectra to [0,1].

Results in undefined behavior to call this function without a preceeding call to libkissinference erroring out. Any subsiquent call to libkissinference invalidates the retuned string.

Parameters

net	The net on which a call failed

Returns: A string describing the error, owned by libkissinference, do not free.

◆ kiss_grad()

float kiss_grad	(	float *	data,
		float *	omegas,
		size_t	input_length,
		size_t	index )

Approximates the gradiant at the given index.

Parameters

data	An array of floats on which to calculate the gradiant.
input_length	The length of the input data.
index	The index at which to aproxmiate the gradiant.

◆ kiss_linear()

void kiss_linear	(	float *	data,
		float *	weight,
		float *	bias,
		size_t	lengh )

Applies a linear nn layer to the given input.

Parameters

data	An array of floats to calculate linear layer on.
weight	the weights of the layer.
bias	the biases of the layer.
length	the length of the inputs.

◆ kiss_load_network()

struct kiss_network * kiss_load_network	(	const char *	path,
		void(*	result_cb )(float result, struct kiss_network net, void *user_data),
		bool	verbose )

Loads a network from disk.

If allocation fails this function will return NULL, for all other errors this function will return a network with ready set to false. In this case a detailed error string can be aquired by calling kiss_get_strerror on the network. Any result, except NULL, of this function musst be freed with kiss_free_network().

To avoid leaking memory, the result parameter of result_cb must be freed by result_cb or subsiquently managed by the user of this api.

Parameters

result_cb	A pointer to a callback that will be called after inference is done.
path	A path to a onnx network file.

Returns: a pointer to a newly allocated struct kiss_network to be freed with kiss_free_network() or NULL on allocation failure.

◆ kiss_load_network_from_buffer()

struct kiss_network * kiss_load_network_from_buffer	(	const char *	buffer,
		size_t	size,
		void(*	result_cb )(float result, struct kiss_network net, void *user_data),
		bool	verbose )

Loads a network from a memory address.

This function is the same as kiss_load_network except it takes a in memory buffer to a onnx file instead to a path on disk.

Parameters

result_cb	A pointer to a callback that will be called after inference is done.
buffer	A pointer to a onnx file in memory
size	the size of the given buffer

Returns: a pointer to a newly allocated struct kiss_network to be freed with kiss_free_network() or NULL on allocation failure.

◆ kiss_load_network_from_buffer_prealloc()

bool kiss_load_network_from_buffer_prealloc	(	struct kiss_network *	net,
		const char *	buffer,
		size_t	size,
		void(*	result_cb )(float result, struct kiss_network net, void *user_data),
		bool	verbose )

Loads a network from a memory address.

This function is the same as kiss_load_network_prealloc except it takes a in memory buffer to a onnx file instead to a path on disk.

The resources of resulting network must be freed by kiss_free_network_prealloc.

Parameters

net	a pointer to a allocated kiss_network struct, this pointer must remain valid until after kiss_free_network_prealloc is called.
result_cb	A pointer to a callback that will be called after inference is done.
buffer	A pointer to a onnx file in memory
size	the size of the given buffer

Returns: true on sucess or false on failure, kiss_filter_spectra is set on failure.

◆ kiss_load_network_prealloc()

bool kiss_load_network_prealloc	(	struct kiss_network *	net,
		const char *	path,
		void(*	result_cb )(float result, struct kiss_network net, void *user_data),
		bool	verbose )

Loads a network from disk.

This function is the same as kiss_load_network except that a allocated network struct must be provided. This is usefull where it is desireable to use a different allocator for this struct on the network.

the resources of resulting network must be freed by kiss_free_network_prealloc.

Parameters

net	a pointer to a allocated kiss_network struct, this pointer must remain valid until after kiss_free_network_prealloc is called.
result_cb	A pointer to a callback that will be called after inference is done.
path	A path to a onnx network file.

Returns: true on sucess or false on failure, kiss_filter_spectra is set on failure.

◆ kiss_mean()

float kiss_mean	(	float *	data,
		size_t	input_length )

Calculates the mean of the given data.

Parameters

data	An array of floats to calculate the median on.
input_length	The length of the input data.

Returns: The mean.

◆ kiss_median()

float kiss_median	(	float *	data,
		size_t	input_length )

Calculates the median of the given data.

Parameters

data	An array of floats to calculate the median on.
input_length	The length of the input data.

Returns: The median.

◆ kiss_normalize_spectra()

void kiss_normalize_spectra	(	float *	in_re,
		float *	in_im,
		size_t	input_length )

Normalizes the given spectra to [0,1].

Parameters

in_re	The real part of the input spectra.
in_im	The imaginary part of the input spectra.
input_length	The length of the input spectra.

◆ kiss_reduce_spectra()

bool kiss_reduce_spectra	(	float *	in_re,
		float *	in_im,
		float *	omegas,
		size_t	input_length,
		float	thresh_factor,
		bool	use_second_deriv,
		float **	out_re,
		float **	out_im,
		size_t *	output_length )

Reduces the data by removing "uninteresting" regions.

Uninteresting regions are determined by taking the first and second derivative and removing the areas where these change very little.

Parameters

in_re	The real part of the input spectra.
in_im	The imaginary part of the input spectra.
input_length	The length of the input spectra.
out_re	A pointer where the real part of the reduced spectra will be allocated. to be freed with free().
out_im	A pointer where the imaginary part of the reduced spectra will be allocated. to be freed with free().
output_length	A pointer to a size_t where the new length of the reduced spectra will be stored.
return	returns true if the spectra was reduced sucessfully, false otherwise, dose not set kiss_get_strerror

◆ kiss_resample_spectra()

void kiss_resample_spectra	(	float *	in_re,
		float *	in_im,
		size_t	input_length,
		float **	out_re,
		float **	out_im,
		size_t	output_length )

Resamples a spectra, useing linear interpolation.

Parameters

in_re	The real part of the input spectra.
in_im	The imaginary part of the input spectra.
input_length	The length of the input spectra.
out_re	A pointer where the real part of the resampled spectra will be allocated. to be freed with free().
out_im	A pointer where the imaginary part of the resampled spectra will be allocated. to be freed with free().
output_length	The desired length of the output spectra.

◆ kiss_set_output_mask()

bool kiss_set_output_mask	(	struct kiss_network *	net,
		const bool *	output_mask )

Sets the output mask on a given network.

This function must only be used while no inference requests are pending.

Parameters

net	The network to set the mask on.
output_mask	The output mask to set. The given array must be at least output_size in lengh

Returns: true if the mask was sucessfully set, will return false and set an error for kiss_get_strerror otherwise.

◆ kiss_softmax()

void kiss_softmax	(	float *	data,
		size_t	input_length )

Applies softmax to the given data.

Parameters

data	An array of floats to calculate the softmax on.
input_length	The length of the input data.

◆ kiss_softmax_masked()

void kiss_softmax_masked	(	float *	data,
		bool *	mask,
		size_t	input_length )

Applies softmax to the given data ignoreing the inputs where mask is false.

Parameters

data	An array of floats to calculate the softmax on.
mask	An array of bools, true where the value in data shal be used and false where it shal not. Must be the same length as data.
input_length	The length of the input data.

◆ kiss_start_training()

bool kiss_start_training	(	struct kiss_training_session *	session,
		kiss_loss_t	loss,
		kiss_data_feed_cb_t	datafeeder,
		kiss_data_free_cb_t	datafreeer,
		kiss_train_progress_cb_t	progresscb,
		void *	user_ptr )

Starts training the network.

Parameters

session	The session to be trained.
session	The loss function to use for training.
datafeeder	A callback that libkissinference can call to get data for training.
datafreeer	A callback that libkissinference can call free the data gained by datafeeder.
progresscb	A callback that libkissinference calls to inform the user about training progress and errors.

Returns: True if sucessfull, false otherwise. In case of failure kiss_train_get_strerror is set with a description of the error.

◆ kiss_state_to_str()

const char * kiss_state_to_str ( kiss_train_state_t state )

Gets a description string descrebing the state.

Parameters

state The state to describe.

Returns: A description string, owned by libkissinference do not free.

◆ kiss_train_get_strerror()

const char * kiss_train_get_strerror ( struct kiss_training_session * session )

Gets a error description string descrebing the lass orccured error.

Parameters

session The session in which the error occured

Returns: A error description string, valid untill the next call to libkissinference, owned by libkissinference do not free.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ kiss_data_free_cb_t

◆ kiss_train_progress_cb_t

Enumeration Type Documentation

◆ kiss_train_state_t

Function Documentation

◆ kiss_absgrad()

◆ kiss_async_run_inference()

◆ kiss_create_range()

◆ kiss_create_training_session()

◆ kiss_create_training_session_prealloc()

◆ kiss_create_vector()

◆ kiss_eis_to_cdc()

◆ kiss_eis_to_relaxis()

◆ kiss_filter_spectra()

◆ kiss_finish_training()

◆ kiss_float_eq()

◆ kiss_free()

◆ kiss_free_network()

◆ kiss_free_network_prealloc()

◆ kiss_free_training_session()

◆ kiss_free_training_session_prealloc()

◆ kiss_free_vector()

◆ kiss_get_active_output_count()

◆ kiss_get_strerror()

◆ kiss_grad()

◆ kiss_linear()

◆ kiss_load_network()

◆ kiss_load_network_from_buffer()

◆ kiss_load_network_from_buffer_prealloc()

◆ kiss_load_network_prealloc()

◆ kiss_mean()

◆ kiss_median()

◆ kiss_normalize_spectra()

◆ kiss_reduce_spectra()

◆ kiss_resample_spectra()

◆ kiss_set_output_mask()

◆ kiss_softmax()

◆ kiss_softmax_masked()

◆ kiss_start_training()

◆ kiss_state_to_str()

◆ kiss_train_get_strerror()