MPSolve 3.2.1
Loading...
Searching...
No Matches
context.h File Reference

This file contains the definition of mps_context and most of its fields. More...

#include <mps/mps.h>
#include <pthread.h>

Go to the source code of this file.

Classes

struct  mps_context
 this struct holds the state of the mps computation More...
 

Macros

#define MPS_FNEWTON_PTR(x)   (mps_fnewton_ptr) & (x)
 
#define MPS_DNEWTON_PTR(x)   (mps_dnewton_ptr) & (x)
 
#define MPS_MNEWTON_PTR(x)   (mps_mnewton_ptr) & (x)
 
#define MPS_CHECK_DATA_PTR(x)   (mps_check_data_ptr) & (x)
 
#define MPS_FSTART_PTR(x)   (mps_fstart_ptr) & (x)
 
#define MPS_DSTART_PTR(x)   (mps_dstart_ptr) & (x)
 
#define MPS_MPSOLVE_PTR(x)   (mps_mpsolve_ptr) & (x)
 

Typedefs

typedef void(* mps_mpsolve_ptr) (mps_context *status)
 Routine that performs the computation loop to solve the polynomial or the secular equation.
 
typedef void *(* mps_callback) (mps_context *status, void *user_data)
 Pointer to the callback for the async version of mpsolve.
 

Functions

mps_contextmps_context_new (void)
 Allocate a new mps_context struct with default options.
 
void mps_context_free (mps_context *s)
 Free a not more useful mps_context. More...
 
void mps_context_abort (mps_context *s)
 
int mps_context_set_poly_d (mps_context *s, cplx_t *coeff, long unsigned int n)
 Set active polynomial as a real floating point coefficient polynomial of degree n with coefficient exactly determined by components of vector coeff. More...
 
void mps_context_set_input_poly (mps_context *s, mps_polynomial *p)
 Set the monomial poly p as the input polynomial for the current equation. More...
 
int mps_context_set_poly_i (mps_context *s, int *coeff, long unsigned int n)
 Set active polynomial as a integer coefficient polynomial of degree n with coefficient exactly determined by components of vector coeff. More...
 
void mps_context_select_algorithm (mps_context *s, mps_algorithm algorithm)
 Select algorithm to use for computation. More...
 
void mps_context_set_degree (mps_context *s, int n)
 
void mps_context_allocate_poly_inplace (mps_context *s, int n)
 
long int mps_context_get_data_prec_max (mps_context *s)
 
long int mps_context_get_minimum_precision (mps_context *s)
 
int mps_context_get_degree (mps_context *s)
 
int mps_context_get_roots_d (mps_context *s, cplx_t **roots, double **radius)
 Set roots[i] to the i-th root of the polynomial and (if it is not NULL) radius[i] to the i-th inclusion radius. More...
 
int mps_context_get_roots_m (mps_context *s, mpc_t **roots, rdpe_t **radius)
 Get the roots computed as multiprecision complex numbers. More...
 
int mps_context_get_zero_roots (mps_context *s)
 Get the number of zero roots in the output. Must be called after mps_mpsolve() has complete. More...
 
mps_root_status mps_context_get_root_status (mps_context *ctx, int i)
 Retrieve the status of the root in position i. More...
 
mps_boolean mps_context_get_over_max (mps_context *s)
 Return true of the computation has passed the maximum admitted precision, and so was unable to reach desired output precision without any further information on the input coefficients. More...
 
mps_polynomialmps_context_get_active_poly (mps_context *ctx)
 Retrieve a pointer to the active polynomial being solved. More...
 
mps_approximation ** mps_context_get_approximations (mps_context *ctx)
 Retrieve a pointer to the current approximations in the context. More...
 
void mps_context_set_input_prec (mps_context *s, long int prec)
 Set the bits of precision of the input coefficients. More...
 
void mps_context_set_output_prec (mps_context *s, long int prec)
 Set the output precision for the roots. More...
 
void mps_context_set_output_format (mps_context *s, mps_output_format format)
 Set the desired output format that will be used when calling mps_output(). More...
 
void mps_context_set_output_goal (mps_context *s, mps_output_goal goal)
 Set the output goal for the computation. More...
 
void mps_context_set_starting_phase (mps_context *s, mps_phase phase)
 Set the phase from which the computation should start. More...
 
void mps_context_set_log_stream (mps_context *s, FILE *logstr)
 Set logstr as the default output for logging. More...
 
void mps_context_set_jacobi_iterations (mps_context *s, mps_boolean jacobi_iterations)
 Set the value of the jacobi iterations switch in the MPSolve context. More...
 
void mps_context_select_starting_strategy (mps_context *s, mps_starting_strategy strategy)
 Select the starting strategy used to dispose the initial approximations.
 
void mps_context_set_avoid_multiprecision (mps_context *s, mps_boolean avoid_multiprecision)
 Set the internal flag "avoid_multiprecision" to the specified value. More...
 
void mps_context_set_crude_approximation_mode (mps_context *s, mps_boolean crude_approximation_mode)
 Enable the "crude" only approximation mode of MPSolve. More...
 
void mps_context_set_regeneration_driver (mps_context *s, mps_regeneration_driver *rd)
 Select the regeneration driver implementation to use. More...
 
void mps_context_set_debug_level (mps_context *s, mps_debug_level level)
 Set the debug level in MPSolve. More...
 
void mps_context_add_debug_domain (mps_context *s, mps_debug_level level)
 Add another debug domain to the ones displayed. This will enable debug if disabled and show message from the given region. More...
 
mps_input_configurationmps_context_get_input_config (mps_context *s)
 Get a pointer to the input config stored in the given mps_context. More...
 
mps_output_configurationmps_context_get_output_config (mps_context *s)
 Get a pointer to the output config stored in the given mps_context. More...
 
mps_boolean mps_context_has_errors (mps_context *s)
 Return true if mpsolve has encountered an error in the computation. More...
 
char * mps_context_error_msg (mps_context *s)
 Return a copy of the string describing the error msg, or NULL if no error has been encountered. More...
 

Detailed Description

This file contains the definition of mps_context and most of its fields.

Function Documentation

◆ mps_context_add_debug_domain()

void mps_context_add_debug_domain ( mps_context s,
mps_debug_level  level 
)

Add another debug domain to the ones displayed. This will enable debug if disabled and show message from the given region.

Parameters
sThe mps_context of the current computation.
levelThe domain to add to the already set debug_level.

◆ mps_context_error_msg()

char * mps_context_error_msg ( mps_context s)

Return a copy of the string describing the error msg, or NULL if no error has been encountered.

This char array should be freed by the user.

Parameters
sThe mps_context of the current computation.

◆ mps_context_free()

void mps_context_free ( mps_context s)

Free a not more useful mps_context.

Parameters
sthe mps_context struct pointer to free.

◆ mps_context_get_active_poly()

mps_polynomial * mps_context_get_active_poly ( mps_context ctx)

Retrieve a pointer to the active polynomial being solved.

Returns
A pointer to the requested active polynomial.

◆ mps_context_get_approximations()

mps_approximation ** mps_context_get_approximations ( mps_context ctx)

Retrieve a pointer to the current approximations in the context.

Parameters
ctxThe current mps_context.
Returns
A vector of n mps_approximation pointer, where n is the degree of the current polynomial that can be retrieve with mps_context_get_degree().

Note that the value returned is a copy of the original approximations, so it should be freed when not needed anymore.

Also note that mps_approximation_free() need the context where the approximations were created to proceed, so you should free those approximaitions before freeing the context.

◆ mps_context_get_input_config()

mps_input_configuration * mps_context_get_input_config ( mps_context s)

Get a pointer to the input config stored in the given mps_context.

Parameters
sThe mps_context of the current computation.

◆ mps_context_get_output_config()

mps_output_configuration * mps_context_get_output_config ( mps_context s)

Get a pointer to the output config stored in the given mps_context.

Parameters
sThe mps_context of the current computation.

◆ mps_context_get_over_max()

mps_boolean mps_context_get_over_max ( mps_context s)

Return true of the computation has passed the maximum admitted precision, and so was unable to reach desired output precision without any further information on the input coefficients.

Parameters
sThe mps_context of the current computation.

◆ mps_context_get_root_status()

mps_root_status mps_context_get_root_status ( mps_context ctx,
int  i 
)

Retrieve the status of the root in position i.

This method can be used to obtain more insight on the status of the approximations previously obtained by a call to mps_context_get_roots_m() or mps_context_get_roots_d().

Returns
A copy to the mps_root_status of the approximation.

◆ mps_context_get_roots_d()

int mps_context_get_roots_d ( mps_context s,
cplx_t **  roots,
double **  radius 
)

Set roots[i] to the i-th root of the polynomial and (if it is not NULL) radius[i] to the i-th inclusion radius.

Parameters
sThe current mps_context.
rootsA pointer to an array of cplx_t variables. if *roots == NULL, MPSolve will take care of allocating these for you. You are in charge to free them when you don't need them anymore.
radiusA pointer to an array of double where MPSolve should store the inclusion radii. If *radius == NULL MPSolve will allocate those radii for you. If radius == NULL no radii will be returned.

◆ mps_context_get_roots_m()

int mps_context_get_roots_m ( mps_context s,
mpc_t **  roots,
rdpe_t **  radius 
)

Get the roots computed as multiprecision complex numbers.

Parameters
rootsA pointer to an array of mpc_t variables. if *roots == NULL, MPSolve will take care of allocate and init those for you. You are in charge to free and clear them when you don't need them anymore.
radiusA pointer to an array of rdpe_t where MPSolve should store the inclusion radii. If *radius == NULL MPSolve will allocate those radii for you. If radius == NULL no radii will be returned.

◆ mps_context_get_zero_roots()

int mps_context_get_zero_roots ( mps_context s)

Get the number of zero roots in the output. Must be called after mps_mpsolve() has complete.

Parameters
sThe mps_context of the current computation.

◆ mps_context_has_errors()

mps_boolean mps_context_has_errors ( mps_context s)

Return true if mpsolve has encountered an error in the computation.

Parameters
sThe mps_context of the current computation.

◆ mps_context_select_algorithm()

void mps_context_select_algorithm ( mps_context s,
mps_algorithm  algorithm 
)

Select algorithm to use for computation.

Valid values for this field are

  • MPS_ALGORITHM_STANDARD_MPSOLVE for the standard MPSolve algorithm;
  • MPS_ALGORITHM_SECULAR_GA for the algorithm based on coefficient regeneration applied to secular equations;

◆ mps_context_set_avoid_multiprecision()

void mps_context_set_avoid_multiprecision ( mps_context s,
mps_boolean  avoid_multiprecision 
)

Set the internal flag "avoid_multiprecision" to the specified value.

If avoid_multiprecision is true MPSolve will not enter a multiprecision stage thus making impossible the computation of more digits than the one that are representable in standard floating point.

This may be a useful flag to approximate roots of very ill-conditioned polynomials of high degree when no strict isolation is required. In this case it's possible to obtain very good approximations that are not Newton-isolated but are still satisfactory.

◆ mps_context_set_crude_approximation_mode()

void mps_context_set_crude_approximation_mode ( mps_context s,
mps_boolean  crude_approximation_mode 
)

Enable the "crude" only approximation mode of MPSolve.

If this mode is activated MPSolve will only perform a basic Aberth iteration in floating point and then exit. Note that the output result will still be guaranteed but in general it will not be possible to reach arbitrary precision and the results may be quite far from the roots for bad conditioned polynomials.

◆ mps_context_set_debug_level()

void mps_context_set_debug_level ( mps_context s,
mps_debug_level  level 
)

Set the debug level in MPSolve.

Parameters
sThe mps_context of the current computation.
levelThe debug_level to set.

◆ mps_context_set_input_poly()

void mps_context_set_input_poly ( mps_context s,
mps_polynomial p 
)

Set the monomial poly p as the input polynomial for the current equation.

Parameters
sThe mps_context to set the monomial_poly into.
pThe mps_monomial_poly to solve.

◆ mps_context_set_input_prec()

void mps_context_set_input_prec ( mps_context s,
long int  prec 
)

Set the bits of precision of the input coefficients.

This has meaning only for fp coefficients, and the special value 0 means infinite precision.

Parameters
sThe mps_context of the current computation.
precThe precisision to be set.

◆ mps_context_set_jacobi_iterations()

void mps_context_set_jacobi_iterations ( mps_context s,
mps_boolean  jacobi_iterations 
)

Set the value of the jacobi iterations switch in the MPSolve context.

If jacobi_iterations is true then the Ehrlich-Aberth iterations will be carried out in a Jacobi fashion, otherwise Gauss-Seidel style will be employed.

Parameters
sThe mps_context where the value will be set
jacobi_iterationsThe desired value for the jacobi_iterations switch.

◆ mps_context_set_log_stream()

void mps_context_set_log_stream ( mps_context s,
FILE *  logstr 
)

Set logstr as the default output for logging.

Parameters
sThe mps_context of the current computation.
logstrThe desired stream to be used for logging.

◆ mps_context_set_output_format()

void mps_context_set_output_format ( mps_context s,
mps_output_format  format 
)

Set the desired output format that will be used when calling mps_output().

Parameters
sThe mps_context of the current computation.
formatThe format chosen for the output.

◆ mps_context_set_output_goal()

void mps_context_set_output_goal ( mps_context s,
mps_output_goal  goal 
)

Set the output goal for the computation.

Parameters
sThe mps_context of the computation.
goalThe goal that will be reached before stopping.

◆ mps_context_set_output_prec()

void mps_context_set_output_prec ( mps_context s,
long int  prec 
)

Set the output precision for the roots.

This has different meaning based on the output goal. If the goal is MPS_OUTPUT_GOAL_ISOLATE, this is the maximum precision used to try to isolate the roots, but roots won't be approximated at this precision if they are isolated with less precision.

If the goal is MPS_OUTPUT_GOAL_APPROXIMATE, this is the minimum precision required for the roots in output.

Parameters
sThe mps_context of the computation.
precThe desired output precision.

◆ mps_context_set_poly_d()

int mps_context_set_poly_d ( mps_context s,
cplx_t *  coeff,
long unsigned int  n 
)

Set active polynomial as a real floating point coefficient polynomial of degree n with coefficient exactly determined by components of vector coeff.

Precisely, if ${\mathrm coeff}$ is a vector of $n+1$ components,

\[
  p(x) = \sum_{i = 0}^{n} {\mathrm coeff}_i  x^i
\]

◆ mps_context_set_poly_i()

int mps_context_set_poly_i ( mps_context s,
int *  coeff,
long unsigned int  n 
)

Set active polynomial as a integer coefficient polynomial of degree n with coefficient exactly determined by components of vector coeff.

Precisely, if ${\mathrm coeff}$ is a vector of $n+1$ components,

\[
  p(x) = \sum_{i = 0}^{n} {\mathrm coeff}_i  x^i
\]

◆ mps_context_set_regeneration_driver()

void mps_context_set_regeneration_driver ( mps_context s,
mps_regeneration_driver rd 
)

Select the regeneration driver implementation to use.

The user of the library can change the default regeneration driver by providing a custom implementation of mps_regeneration_driver and calling this function.

The custom implementation is obtained by hooking the function pointers defined in mps_regeneration_driver to custom routines that update a secular equation given new nodes.

As usual, three routines for every data type supported by MPSolve must be provided.

Parameters
sThe context where the change will have effect.
rdThe custom regeneration driver. Optionally this field may be NULL to restore the default implementation.

◆ mps_context_set_starting_phase()

void mps_context_set_starting_phase ( mps_context s,
mps_phase  phase 
)

Set the phase from which the computation should start.

Parameters
sThe mps_context of the current computation.
phaseThe phase which should be chosen at the start of the computation.