HEAD PREVIOUS

5  LMie C Interface

The LMie C interface is made available by including src/lmie_interface.h in your code. It consists of some enumeration constants, input and output structures as typedefs, and functions for managing memory used in the structures and to call the actual Mie scattering algorithm.
In a typical usage the steps taken to use LMie will be:
  1. Allocate memory used by the lmie_in_data input structure with lmie_in_alloc().
  2. If derivatives are to be computed, zero out all the linearized inputs in the lmie_in_data input structure with lmie_in_zero_derivs().
  3. Set the input values in the lmie_in_data input structure including any nonzero linearized values when derivatives are to be computed
  4. Call lmie_solution() to calculate the Mie scattering results.
  5. Read/use the output values from the lmie_out_data output structure.
  6. Free memory allocated to the lmie_out_data output structure with lmie_out_free().
  7. If another set of results is required and the number of derivatives has not changed loop back to step 2.
  8. Free memory allocated to the lmie_in_data input structure with lmie_in_free()
See examples/example_c.c for an actual example of LMie usage in C.

5.1  Size distributions

Size distributions are indicated by the following enumeration constants:
SIZE_DIST_MONO
SIZE_DIST_GAMMA
SIZE_DIST_MODIFIED_GAMMA
SIZE_DIST_POWER_LAW
SIZE_DIST_MODIFIED_POWER_LAW
SIZE_DIST_LOG_NORMAL
SIZE_DIST_MODIFIED_BIMODAL_LOG_NORMAL

5.2  Input and output structures

The LMie input structure typedef is:
typedef struct {
int calc_gc;
int calc_lc;
int calc_pf;
enum size_dist_type dist_type;
int n_int1;
int n_int2;
int n_quad;
int n_angles;
int n_derivs;
double lambda;
double mr;
double mi;
double a1;
double a2;
double a3;
double a4;
double a5;
double r1;
double r2;
double *lambda_l;
double *mr_l;
double *mi_l;
double *a1_l;
double *a2_l;
double *a3_l;
double *a4_l;
double *a5_l;
double *r1_l;
double *r2_l;
double accuracy;
} lmie_in_data;
The LMie output structure typedef is:
typedef struct {
int n_coef;
double r1;
double r2;
double norm;
double reff;
double veff;
double gavg;
double vavg;
double ravg;
double rvw;
double cext;
double csca;
double cbak;
double g;
double **gc;
double **lc;
double *theta;
double **pf;
double *r1_l;
double *r2_l;
double *norm_l;
double *reff_l;
double *veff_l;
double *gavg_l;
double *vavg_l;
double *ravg_l;
double *rvw_l;
double *cext_l;
double *csca_l;
double *cbak_l;
double *g_l;
double ***gc_l;
double ***lc_l;
double ***pf_l;
} lmie_in_data;

5.3  Function interface

int lmie_in_alloc(lmie_in_data *in, int n_derivs)

Description:
Allocate memory used by an lmie_in_data input structure. This function should be called before populating an lmie_in_data input structure before the first call to lmie_solution(). After calling this function all pointers within the lmie_in_data input structure may be used as valid arrays over subsequent calls to lmie_solution() as long as n_derivs does not change. Once use of the lmie_in_data input structure is finished lmie_in_free() must be called to free the allocated memory.
Arguments:
in    an lmie_in_data input structure for which to allocate memory
n_derivs    the number of derivatives for which to allocate memory
Return value:
Zero with successful completion or otherwise on error.

void lmie_in_free(lmie_in_data *in, int flag)

Description:
Free memory allocated to an lmie_in_data input structure by lmie_in_alloc(). This function should be called after use of an lmie_in_data input structure is finished.
Arguments:
in    an lmie_in_data input structure for which to free memory
flag    zero if the number of derivatives is zero and nonzero otherwise
Return value:
None.

void lmie_out_free(lmie_out_data *out, int flag)

Description:
Free memory allocated to an lmie_out_data output structure by lmie_solution(). This function should be called after use of the output data within the lmie_out_data output structure is finished and before another call to lmie_solution() otherwise the allocated memory from the previous call will be leaked.
Arguments:
out    an lmie_out_data output structure for which to free memory
flag    zero if the number of derivatives is zero and nonzero otherwise
Return value:
None.

void lmie_in_zero_derivs(lmie_in_data *in, int n_derivs)

Description:
Sets all the linearized inputs (derivatives) in an lmie_in_data input structure to zero. This function is not necessary and is provided as convenience since in many cases most of the linearized inputs are set to zero. This function must be called after a call to lmie_in_alloc().
Arguments:
in    an lmie_in_data input structure for which to zero the linearized inputs
Return value:
None.

int lmie_solution(lmie_in_data *in, lmie_out_data *out, int alloc_out, int verbose, int n_threads, int use_mpi)

Description:
Run the actual Mie scattering algorithm using the inputs in the supplied input structure and put the outputs in the supplied output structure.
Arguments:
in    the lmie_in_data input structure
out    the lmie_out_data output structure
alloc_out    Flag indicating whether or not memory should be allocated for the lmie_out_data output structure. This should only be set to "false" if enough memory has already been allocated for the lmie_out_data output structure, either by the user or from a subsequent call to lmie_solution(). The amount of memory used is dependent on the input value r2 so that an initial call to lmie_solution() using a maximum value for r2 will allocate enough memory for subsequent calls with a lesser or equal value of r2.
n_threads    Number of threads to use. For minimum run times the number of threads should be set to the number of cores available on the machine being used.
use_mpi    A flag indicating whether or not to use MPI. This requires the execution of two or more separate calling processes using the appropriate MPI execution program. MPI parallelization is above the threaded parallelization in which case n_threads indicates the number of threads to use per MPI process.
verbose    A flag indicating whether or not to print information useful for debugging. Currently only information useful for debugging calls using MPI is printed.
Return value:
Zero with successful completion or otherwise on error.

5.4  Example C program using LMie

An example program using the C interface is at 
     examples/example_c.c
and when the LMie code is compiled properly the C example program will be compiled as 
     examples/example_c
HEAD NEXT