Context

1. Context
2. Precision

This file is written in C because it is more natural to express the context in C than in Fortran.

3 files are produced:

a header file : qmckl_context.h
a source file : qmckl_context.c
a test file : test_qmckl_context.c

1 Context

The context variable is a handle for the state of the library, and is stored in the following data structure, which can't be seen outside of the library. To simplify compatibility with other languages, the pointer to the internal data structure is converted into a 64-bit signed integer, defined in the qmckl_context type. A value of 0 for the context is equivalent to a NULL pointer.

1.0.1 Source

typedef struct qmckl_context_struct {
  struct qmckl_context_struct * prev;
  uint32_t tag;
  int32_t precision;
  int32_t range;
} qmckl_context_struct;

#define VALID_TAG   0xBEEFFACE
#define INVALID_TAG 0xDEADBEEF

The tag is used internally to check if the memory domain pointed by a pointer is a valid context.

1.1 `qmckl_context_check`

Checks if the domain pointed by the pointer is a valid context. Returns the input qmckl_context if the context is valid, 0 otherwise.

1.1.1 Header

qmckl_context qmckl_context_check(const qmckl_context context) ;

1.1.2 Source

qmckl_context qmckl_context_check(const qmckl_context context) {
  qmckl_context_struct * ctx;

  if (context == (qmckl_context) 0) return (qmckl_context) 0;

  ctx = (qmckl_context_struct*) context;
  if (ctx->tag != VALID_TAG) return (qmckl_context) 0;

  return context;
}

1.2 `qmckl_context_create`

To create a new context, use qmckl_context_create().

On success, returns a pointer to a context using the qmckl_context type
Returns 0 upon failure to allocate the internal data structure

1.2.1 Header

qmckl_context qmckl_context_create();

1.2.2 Source

qmckl_context qmckl_context_create() {

  qmckl_context_struct*  context;

  context = (qmckl_context_struct*) qmckl_malloc ((qmckl_context) 0, sizeof(qmckl_context_struct));
  if (context == NULL) {
    return (qmckl_context) 0;
  }

  context->prev      = NULL;
  context->precision = QMCKL_DEFAULT_PRECISION;
  context->range     = QMCKL_DEFAULT_RANGE;
  context->tag       = VALID_TAG;

  return (qmckl_context) context;
}

1.3 `qmckl_context_copy`

This function makes a shallow copy of the current context.

Copying the 0-valued context returns 0
On success, returns a pointer to the new context using the qmckl_context type
Returns 0 upon failure to allocate the internal data structure for the new context

1.3.1 Header

qmckl_context qmckl_context_copy(const qmckl_context context);

1.3.2 Source

qmckl_context qmckl_context_copy(const qmckl_context context) {

  qmckl_context_struct* old_context;
  qmckl_context_struct* new_context;
  qmckl_context checked_context;

  checked_context = qmckl_context_check(context);

  if (checked_context == (qmckl_context) 0) {
    return (qmckl_context) 0;
  }

  new_context = (qmckl_context_struct*) qmckl_malloc (context, sizeof(qmckl_context_struct));
  if (new_context == NULL) {
    return (qmckl_context) 0;
  }

  old_context = (qmckl_context_struct*) checked_context;

  new_context->prev      = old_context;
  new_context->precision = old_context->precision;
  new_context->range     = old_context->range;
  new_context->tag       = VALID_TAG;

  return (qmckl_context) new_context;
}

1.4 `qmckl_context_previous`

Returns the previous context

On success, returns the ancestor of the current context
Returns 0 for the initial context
Returns 0 for the 0-valued context

1.4.1 Header

qmckl_context qmckl_context_previous(const qmckl_context context);

1.4.2 Source

qmckl_context qmckl_context_previous(const qmckl_context context) {

  qmckl_context checked_context;
  qmckl_context_struct* ctx;

  checked_context = qmckl_context_check(context);
  if (checked_context == (qmckl_context) 0) {
    return (qmckl_context) 0;
  }

  ctx = (qmckl_context_struct*) checked_context;
  return qmckl_context_check((qmckl_context) ctx->prev);
}

1.5 `qmckl_context_destroy`

Destroys the current context, leaving the ancestors untouched.

Succeeds if the current context is properly destroyed
Fails otherwise
Fails if the 0-valued context is given in argument
Fails if the the pointer is not a valid context

1.5.1 Header

qmckl_exit_code qmckl_context_destroy(qmckl_context context);

1.5.2 Source

qmckl_exit_code qmckl_context_destroy(qmckl_context context) {

  qmckl_context_struct* ctx;
  qmckl_context checked_context;

  checked_context = qmckl_context_check(context);
  if (checked_context == (qmckl_context) 0) return QMCKL_FAILURE;

  ctx = (qmckl_context_struct*) context;
  if (ctx == NULL) return QMCKL_FAILURE;

  ctx->tag = INVALID_TAG;
  qmckl_free(ctx);
  return QMCKL_SUCCESS;
}

2 Precision

The following functions set and get the expected required precision and range. precision should be an integer between 2 and 53, and range should be an integer between 2 and 11.

The setter functions functions return a new context as a 64-bit integer. The getter functions return the value, as a 32-bit integer. The update functions return QMCKL_SUCCESS or QMCKL_FAILURE.

2.1 `qmckl_context_update_precision`

2.1.1 Source

qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision);

qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision) {
  qmckl_context_struct* ctx;

  if (precision <  2) return QMCKL_FAILURE;
  if (precision > 53) return QMCKL_FAILURE;

  ctx = (qmckl_context_struct*) context;
  if (ctx == NULL) return QMCKL_FAILURE;

  ctx->precision = precision;
  return QMCKL_SUCCESS;
}

2.2 `qmckl_context_update_range`

2.2.1 Source

qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const int range);

qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const int range) {
  qmckl_context_struct* ctx;

  if (range <  2) return QMCKL_FAILURE;
  if (range > 11) return QMCKL_FAILURE;

  ctx = (qmckl_context_struct*) context;
  if (ctx == NULL) return QMCKL_FAILURE;

  ctx->range = range;
  return QMCKL_SUCCESS;
}

2.3 `qmckl_context_set_precision`

2.3.1 Source

qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision);

qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision) {
  qmckl_context new_context;

  new_context = qmckl_context_copy(context);
  if (new_context == 0) return 0;

  if (qmckl_context_update_precision(context, precision) == QMCKL_FAILURE) return 0;

  return new_context;
}

2.4 `qmckl_context_set_range`

2.4.1 Source

qmckl_context qmckl_context_set_range(const qmckl_context context, const int range);

qmckl_context qmckl_context_set_range(const qmckl_context context, const int range) {
  qmckl_context new_context;

  new_context = qmckl_context_copy(context);
  if (new_context == 0) return 0;

  if (qmckl_context_update_range(context, range) == QMCKL_FAILURE) return 0;

  return new_context;
}

2.5 `qmckl_context_get_precision`

2.5.1 Source

int qmckl_context_get_precision(const qmckl_context context);

int qmckl_context_get_precision(const qmckl_context context) {
  qmckl_context_struct* ctx;
  ctx = (qmckl_context_struct*) context;
  return ctx->precision;
}

2.6 `qmckl_context_get_range`

2.6.1 Source

int qmckl_context_get_range(const qmckl_context context);

int qmckl_context_get_range(const qmckl_context context) {
  qmckl_context_struct* ctx;
  ctx = (qmckl_context_struct*) context;
  return ctx->range;
}