The C language bindings for the ZerSol C++ library functions. More...

#include <complex.h>

Macros
#define	_Real double
	_Real is a convenient alias for the real number type. Possible values: float, double (recommended).

#define	IU _Complex_I
	IU is a convenient alias for the imaginary unit.

Typedefs
typedef _Real	_real_
	_real_ is typedef for real numbers for the ZerSol C interface.

typedef _Real _Complex	_complex_
	_complex_ is typedef for complex numbers for the ZerSol C interface.

typedef _complex_(*	complex_function )(_complex_, void *)
	complex_function is typedef for complex functions for the ZerSol C interface.

Functions
_complex_	template_function (_complex_ z, void *p)
	The template for a complex analytic function and its derivative.

void *	create_solver (complex_function f, complex_function df, void data, char const description, _real_ xmin, _real_ xmax, _real_ ymin, _real_ ymax)
	Create a data structure needed for the subsequent calls of the solver functions.

int	find_zeros (void solver, int N, _complex_ Z, _complex_ V, int n_zeros)
	Run the zeros search procedure.

void	print_status (void solver, const char file_name)
	Print the status of the zeros search.

void	print_dump (void solver, const char file_name)
	Print the dump of the solver data.

void	free_solver (void *solver)
	Free the memory allocated by the solver.

void	set_nd_method (void *solver, int method)
	Set a finite difference method for numerical evaluation of the function derivative.

void	set_nd_step (void *solver, _real_ h)
	Set a step size (dz) for numerical evaluation of the function derivative.

void	set_min_rec_lev (void *solver, int min_rec_lev)
	Set the minimum recursion level for the winding number evaluation procedure.

void	set_max_rec_lev (void *solver, int max_rec_lev)
	Set the maximum recursion level for the winding number evaluation procedure.

void	set_interp_err (void *solver, _real_ interp_err)
	Set a tolerance of interpolation for the winding number evaluation procedure.

void	set_jump_err (void *solver, _real_ jump_err)
	Set a tolerance of test for discontinuities for the winding number evaluation procedure.

void	set_n_target (void *solver, int n_target)
	Set a desired number of the function zeros.

void	set_start_array (void solver, int n_start, _complex_ start)
	Set the array of a user supplied starting values for the Newton's iterations.

void	set_n_split_x (void *solver, int n_split_x)
	Set the number of automatic starting points along Re{z}.

void	set_n_split_y (void *solver, int n_split_y)
	Set the number of automatic starting points along Im{z}.

void	set_max_iter_num (void *solver, int max_iter_num)
	Set the maximum number of the Newton's iterations for each starting point.

void	set_multiplicity (void *solver, int multiplicity)
	Set the multiplicity of a zero.

void	set_eps_for_arg (void *solver, _real_ abs_eps_z, _real_ rel_eps_z)
	Set the absolute and relative tolerances for the convergence condition on z.

void	set_eps_for_func (void *solver, _real_ abs_eps_f, _real_ rel_eps_f)
	Set the absolute and relative tolerances for the convergence condition on f(z).

void	set_use_winding (void *solver, int use_winding)
	Set a flag that defines whether the solver will use the winding number evaluation or just Newton iterations.

void	set_max_part_level (void *solver, int max_part_level)
	Set the maximum allowed level of the rectangle partition.

void	set_debug_level (void *solver, int debug_level)
	Set the debug level (determines the amount of internal checks).

void	set_print_level (void *solver, int print_level)
	Set the print level (determines the amount of details printed).

int	get_nd_method (void *solver)
	Get a finite difference method for numerical evaluation of the function derivative.

_real_	get_nd_step (void *solver)
	Get a step size (dz) for numerical evaluation of the function derivative.

int	get_min_rec_lev (void *solver)
	Get the minimum recursion level for the winding number evaluation procedure.

int	get_max_rec_lev (void *solver)
	Get the maximum recursion level for the winding number evaluation procedure.

_real_	get_interp_err (void *solver)
	Get a tolerance of interpolation for the winding number evaluation procedure.

_real_	get_jump_err (void *solver)
	Get a tolerance of test for discontinuities for the winding number evaluation procedure.

int	get_n_target (void *solver)
	Get a desired number of the function zeros.

void	get_start_array (void solver, int n_start, _complex_ **start)
	Get the array of a user supplied starting values for the Newton's iterations.

int	get_n_split_x (void *solver)
	Get the number of automatic starting points along Re{z}.

int	get_n_split_y (void *solver)
	Get the number of automatic starting points along Im{z}.

int	get_max_iter_num (void *solver)
	Get the maximum number of the Newton's iterations for each starting point.

int	get_multiplicity (void *solver)
	Get the multiplicity of a zero.

void	get_eps_for_arg (void solver, _real_ abs_eps_z, _real_ *rel_eps_z)
	Get the absolute and relative tolerances for the convergence condition on z.

void	get_eps_for_func (void solver, _real_ abs_eps_f, _real_ *rel_eps_f)
	Get the absolute and relative tolerances for the convergence condition on f(z).

int	get_use_winding (void *solver)
	Get a flag that defines whether the solver will use the winding number evaluation or just Newton iterations.

int	get_max_part_level (void *solver)
	Get the maximum allowed level of the rectangle partition.

int	get_debug_level (void *solver)
	Get the debug level (determines the amount of internal checks).

int	get_print_level (void *solver)
	Get the print level (determines the amount of details printed).

Detailed Description

The C language bindings for the ZerSol C++ library functions.

It is recommended to use the ZerSol typedefs _real_ and _complex_ for real and complex numbers to ensure the consistence of your data types with those used in ZerSol C bindings.

You can change the type of floating point numbers in zersolc.h in the line:

#define _Real double

Don't forget to rebuild the ZerSol C bindings after that!

Macro Definition Documentation

#define _Real double

_Real is a convenient alias for the real number type. Possible values: float, double (recommended).

#define IU _Complex_I

IU is a convenient alias for the imaginary unit.

Typedef Documentation

typedef _Real _real_

_real_ is typedef for real numbers for the ZerSol C interface.

typedef _Real _Complex _complex_

_complex_ is typedef for complex numbers for the ZerSol C interface.

typedef _complex_(* complex_function)(_complex_, void *)

complex_function is typedef for complex functions for the ZerSol C interface.

Function Documentation

_complex_ template_function	(	_complex_	z,
		void *	p
	)

The template for a complex analytic function and its derivative.

Parameters

z	value of independent complex variable
p	pointer to an object that can be used to pass any additional parameters into the function

Returns: function value at z

void* create_solver	(	complex_function	f,
		complex_function	df,
		void *	data,
		char const *	description,
		_real_	xmin,
		_real_	xmax,
		_real_	ymin,
		_real_	ymax
	)

Create a data structure needed for the subsequent calls of the solver functions.

Parameters

f	name of a C function that evaluates the complex function value
df	name of a C function that evaluates the complex function derivative
data	pointer to a structure that can be used to pass any data into the function and its derivative
description	string that indicates the function purpose
xmin	minimum x-coordinate of the rectangular region
xmax	maximum x-coordinate of the rectangular region
ymin	minimum y-coordinate of the rectangular region
ymax	maximum y-coordinate of the rectangular region

Returns: pointer to the solver structure

int find_zeros	(	void *	solver,
		int	N,
		_complex_ *	Z,
		_complex_ *	V,
		int *	n_zeros
	)

Run the zeros search procedure.

Parameters

solver	pointer to the solver structure
N	length of the passed Z and V arrays
Z	array for the function zeros
V	array for the function values V = F(Z)
n_zeros	number of the zeros found

Returns: search status

void print_status	(	void *	solver,
		const char *	file_name
	)

Print the status of the zeros search.

Parameters

solver	pointer to the solver structure
file_name	name of a file to print in. The status is printed to stdout if file_name is empty string.

void print_dump	(	void *	solver,
		const char *	file_name
	)

Print the dump of the solver data.

Parameters

solver	pointer to the solver structure
file_name	name of a file to print in. The dump is printed to stdout if file_name is empty string.

void free_solver ( void * solver )

Free the memory allocated by the solver.

Parameters

solver pointer to the solver structure

void set_nd_method	(	void *	solver,
		int	method
	)

Set a finite difference method for numerical evaluation of the function derivative.

Parameters

solver	pointer to the solver structure
method	finite difference method: pass method = 0 for 3-point stencil approximation (second order) and method = 1 for 5-point stencil approximation (fourth order)

void set_nd_step	(	void *	solver,
		_real_	h
	)

Set a step size (dz) for numerical evaluation of the function derivative.

Parameters

solver	pointer to the solver structure
h	step size

void set_min_rec_lev	(	void *	solver,
		int	min_rec_lev
	)

Set the minimum recursion level for the winding number evaluation procedure.

Parameters

solver	pointer to the solver structure
min_rec_lev	minimum recursion level

void set_max_rec_lev	(	void *	solver,
		int	max_rec_lev
	)

Set the maximum recursion level for the winding number evaluation procedure.

Parameters

solver	pointer to the solver structure
max_rec_lev	maximum recursion level

void set_interp_err	(	void *	solver,
		_real_	interp_err
	)

Set a tolerance of interpolation for the winding number evaluation procedure.

Parameters

solver	pointer to the solver structure
interp_err	tolerance of interpolation

void set_jump_err	(	void *	solver,
		_real_	jump_err
	)

Set a tolerance of test for discontinuities for the winding number evaluation procedure.

Parameters

solver	pointer to the solver structure
jump_err	tolerance of test for discontinuities

void set_n_target	(	void *	solver,
		int	n_target
	)

Set a desired number of the function zeros.

Parameters

solver	pointer to the solver structure
n_target	target number of zeros

void set_start_array	(	void *	solver,
		int	n_start,
		_complex_ *	start
	)

Set the array of a user supplied starting values for the Newton's iterations.

Parameters

solver	pointer to the solver structure
n_start	number of starting values
start	array of starting values

void set_n_split_x	(	void *	solver,
		int	n_split_x
	)

Set the number of automatic starting points along Re{z}.

Parameters

solver	pointer to the solver structure
n_split_x	number of starting points

void set_n_split_y	(	void *	solver,
		int	n_split_y
	)

Set the number of automatic starting points along Im{z}.

Parameters

solver	pointer to the solver structure
n_split_y	number of starting points

void set_max_iter_num	(	void *	solver,
		int	max_iter_num
	)

Set the maximum number of the Newton's iterations for each starting point.

Parameters

solver	pointer to the solver structure
max_iter_num	maximum number of iterations

void set_multiplicity	(	void *	solver,
		int	multiplicity
	)

Set the multiplicity of a zero.

Parameters

solver	pointer to the solver structure
multiplicity	expected multiplicity of a zero

void set_eps_for_arg	(	void *	solver,
		_real_	abs_eps_z,
		_real_	rel_eps_z
	)

Set the absolute and relative tolerances for the convergence condition on z.

Parameters

solver	pointer to the solver structure
abs_eps_z	absolute tolerance
rel_eps_z	relative tolerance

void set_eps_for_func	(	void *	solver,
		_real_	abs_eps_f,
		_real_	rel_eps_f
	)

Set the absolute and relative tolerances for the convergence condition on f(z).

Parameters

solver	pointer to the solver structure
abs_eps_f	absolute tolerance
rel_eps_f	relative tolerance

void set_use_winding	(	void *	solver,
		int	use_winding
	)

Set a flag that defines whether the solver will use the winding number evaluation or just Newton iterations.

Parameters

solver	pointer to the solver structure
use_winding	flag: true - use the winding number evaluation, false - use the Newton's iterations only

void set_max_part_level	(	void *	solver,
		int	max_part_level
	)

Set the maximum allowed level of the rectangle partition.

Parameters

solver	pointer to the solver structure
max_part_level	partition level

void set_debug_level	(	void *	solver,
		int	debug_level
	)

Set the debug level (determines the amount of internal checks).

Parameters

solver	pointer to the solver structure
debug_level	debug level

void set_print_level	(	void *	solver,
		int	print_level
	)

Set the print level (determines the amount of details printed).

Parameters

solver	pointer to the solver structure
print_level	print level

int get_nd_method ( void * solver )

Get a finite difference method for numerical evaluation of the function derivative.

Parameters

solver pointer to the solver structure

Returns: finite difference method: method = 0 for 3-point stencil approximation (second order) and method = 1 for 5-point stencil approximation (fourth order)

_real_ get_nd_step ( void * solver )

Get a step size (dz) for numerical evaluation of the function derivative.

Parameters

solver pointer to the solver structure

Returns: step size

int get_min_rec_lev ( void * solver )

Get the minimum recursion level for the winding number evaluation procedure.

Parameters

solver pointer to the solver structure

Returns: minimum recursion level

int get_max_rec_lev ( void * solver )

Get the maximum recursion level for the winding number evaluation procedure.

Parameters

solver pointer to the solver structure

Returns: maximum recursion level

_real_ get_interp_err ( void * solver )

Get a tolerance of interpolation for the winding number evaluation procedure.

Parameters

solver pointer to the solver structure

Returns: tolerance of interpolation

_real_ get_jump_err ( void * solver )

Get a tolerance of test for discontinuities for the winding number evaluation procedure.

Parameters

solver pointer to the solver structure

Returns: tolerance of test for discontinuities

int get_n_target ( void * solver )

Get a desired number of the function zeros.

Parameters

solver pointer to the solver structure

Returns: target number of zeros

void get_start_array	(	void *	solver,
		int *	n_start,
		_complex_ **	start
	)

Get the array of a user supplied starting values for the Newton's iterations.

Parameters

solver	pointer to the solver structure
n_start	number of starting values (pointer to the number)
start	array of starting values (pointer to the array)

int get_n_split_x ( void * solver )

Get the number of automatic starting points along Re{z}.

Parameters

solver pointer to the solver structure

Returns: number of starting points

int get_n_split_y ( void * solver )

Get the number of automatic starting points along Im{z}.

Parameters

solver pointer to the solver structure

Returns: number of starting points

int get_max_iter_num ( void * solver )

Get the maximum number of the Newton's iterations for each starting point.

Parameters

solver pointer to the solver structure

Returns: maximum number of iterations

int get_multiplicity ( void * solver )

Get the multiplicity of a zero.

Parameters

solver pointer to the solver structure

Returns: expected multiplicity of a zero

void get_eps_for_arg	(	void *	solver,
		_real_ *	abs_eps_z,
		_real_ *	rel_eps_z
	)

Get the absolute and relative tolerances for the convergence condition on z.

Parameters

solver	pointer to the solver structure
abs_eps_z	absolute tolerance (pointer)
rel_eps_z	relative tolerance (pointer)

void get_eps_for_func	(	void *	solver,
		_real_ *	abs_eps_f,
		_real_ *	rel_eps_f
	)

Get the absolute and relative tolerances for the convergence condition on f(z).

Parameters

solver	pointer to the solver structure
abs_eps_f	absolute tolerance (pointer)
rel_eps_f	relative tolerance (pointer)

int get_use_winding ( void * solver )

Get a flag that defines whether the solver will use the winding number evaluation or just Newton iterations.

Parameters

solver pointer to the solver structure

Returns: flag: true - use the winding number evaluation, false - use the Newton's iterations only

int get_max_part_level ( void * solver )

Get the maximum allowed level of the rectangle partition.

Parameters

solver pointer to the solver structure

Returns: maximum partition level

int get_debug_level ( void * solver )

Get the debug level (determines the amount of internal checks).

Parameters

solver pointer to the solver structure

Returns: debug level

int get_print_level ( void * solver )

Get the print level (determines the amount of details printed).

Parameters

solver pointer to the solver structure

Returns: print level

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation