From e338930866c922485a0f736d8574d50adb9d5935 Mon Sep 17 00:00:00 2001 From: M Clark Date: Thu, 28 May 2015 10:50:24 -0700 Subject: [PATCH] Added doxygen comments for some milc interface functions and augmented documentation in quda.h --- include/quda.h | 37 +++++++--- include/quda_milc_interface.h | 129 ++++++++++++++++++++++++++++------ 2 files changed, 136 insertions(+), 30 deletions(-) diff --git a/include/quda.h b/include/quda.h index 8c61f8c679..d3b04ae250 100644 --- a/include/quda.h +++ b/include/quda.h @@ -636,7 +636,7 @@ extern "C" { /** * Take a gauge field on the host, load it onto the device and extend it. - * Return a pointer to the extended gauge field. + * Return a pointer to the extended gauge field object. * * @param gauge The CPU gauge field (optional - if set to 0 then the gauge field zeroed) * @param geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) @@ -656,19 +656,21 @@ extern "C" { void* createGaugeFieldQuda(void* gauge, int geometry, QudaGaugeParam* param); /** - * Store a gauge (matrix) field on the device and optionally download a CPU gauge field. + * Copy the QUDA gauge (matrix) field on the device to the CPU * * @param outGauge Pointer to the host gauge field - * @param inGauge Pointer to the device gauge field + * @param inGauge Pointer to the device gauge field (QUDA device field) * @param param The parameters of the host and device fields */ void saveGaugeFieldQuda(void* outGauge, void* inGauge, QudaGaugeParam* param); /** - * Take a gauge field on the device and extend it + * Take a gauge field on the device and copy to the extended gauge + * field. The precisions and reconstruct types can differ between + * the input and output field, but they must be compatible (same volume, geometry). * - * @param outGauge Pointer to the output extended device gauge field - * @param inGauge Pointer to the input device gauge field + * @param outGauge Pointer to the output extended device gauge field (QUDA extended device field) + * @param inGauge Pointer to the input device gauge field (QUDA gauge field) */ void extendGaugeFieldQuda(void* outGauge, void* inGauge); @@ -680,16 +682,19 @@ extern "C" { void destroyGaugeFieldQuda(void* gauge); /** - * Compute the clover field and its inverse from the resident gauge field + * Compute the clover field and its inverse from the resident gauge field. * * @param param The parameters of the clover field to create */ void createCloverQuda(QudaInvertParam* param); /** - * Compute the sigma trace field (part of HMC) + * Compute the sigma trace field (part of clover force computation). + * All the pointers here are for QUDA native device objects. The + * precisions of all fields must match. This function requires that + * there is a persistent clover field. * - * @param out Sigma trace field + * @param out Sigma trace field (QUDA device field, geometry = 1) * @param dummy (not used) * @param mu mu direction * @param nu nu direction @@ -698,7 +703,19 @@ extern "C" { void computeCloverTraceQuda(void* out, void* dummy, int mu, int nu, int dim[4]); /** - * Compute the derivative of the clover term + * Compute the derivative of the clover term (part of clover force + * computation). All the pointers here are for QUDA native device + * objects. The precisions of all fields must match. + * + * @param out Clover derivative field (QUDA device field, geometry = 1) + * @param gauge Gauge field (extended QUDA device field, gemoetry = 4) + * @param oprod Matrix field (outer product) which is multiplied by the derivative + * @param mu mu direction + * @param nu nu direction + * @param coeff Coefficient of the clover derviative (including stepsize and clover coefficient) + * @param parity Parity for which we are computing + * @param param Gauge field meta data + * @param conjugate Whether to make the oprod field anti-hermitian prior to multiplication */ void computeCloverDerivativeQuda(void* out, void* gauge, void* oprod, int mu, int nu, double coeff, diff --git a/include/quda_milc_interface.h b/include/quda_milc_interface.h index 59fe27e6f9..89294bace1 100644 --- a/include/quda_milc_interface.h +++ b/include/quda_milc_interface.h @@ -221,29 +221,118 @@ extern "C" { void* oprod[2]); + /** + * Evolve the gauge field by step size dt, using the momentum field + * I.e., Evalulate U(t+dt) = e(dt pi) U(t). All fields are CPU fields in MILC order. + * + * @param precision Precision of the field (2 - double, 1 - single) + * @param dt The integration step size step + * @param momentum The momentum field + * @param The gauge field to be updated + */ void qudaUpdateU(int precision, - double eps, - void* momentum, - void* link); - - void qudaCloverTrace(void* out, void* clover, int mu, int nu); - - - void qudaCloverDerivative(void* out, void* gauge, void* oprod, - int mu, int nu, double coeff, int precision, int parity, int conjugate); - - - void* qudaCreateExtendedGaugeField(void* gauge, int geometry, int precision); - - void* qudaResidentExtendedGaugeField(void* gauge, int geometry, int precision); - - void* qudaCreateGaugeField(void* gauge, int geometry, int precision); - - void qudaSaveGaugeField(void* gauge, void* inGauge); - + double eps, + void* momentum, + void* link); + + /** + * Compute the sigma trace field (part of clover force computation). + * All the pointers here are for QUDA native device objects. The + * precisions of all fields must match. This function requires that + * there is a persistent clover field. + * + * @param out Sigma trace field (QUDA device field, geometry = 1) + * @param dummy (not used) + * @param mu mu direction + * @param nu nu direction + */ + void qudaCloverTrace(void* out, + void* dummy, + int mu, + int nu); + + + /** + * Compute the derivative of the clover term (part of clover force + * computation). All the pointers here are for QUDA native device + * objects. The precisions of all fields must match. + * + * @param out Clover derivative field (QUDA device field, geometry = 1) + * @param gauge Gauge field (extended QUDA device field, gemoetry = 4) + * @param oprod Matrix field (outer product) which is multiplied by the derivative + * @param mu mu direction + * @param nu nu direction + * @param coeff Coefficient of the clover derviative (including stepsize and clover coefficient) + * @param precision Precision of the fields (2 = double, 1 = single) + * @param parity Parity for which we are computing + * @param conjugate Whether to make the oprod field anti-hermitian prior to multiplication + */ + void qudaCloverDerivative(void* out, + void* gauge, + void* oprod, + int mu, + int nu, + double coeff, + int precision, + int parity, + int conjugate); + + + /** + * Take a gauge field on the host, load it onto the device and extend it. + * Return a pointer to the extended gauge field object. + * + * @param gauge The CPU gauge field (optional - if set to 0 then the gauge field zeroed) + * @param geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param precision The precision of the fields (2 - double, 1 - single) + * @return Pointer to the gauge field (cast as a void*) + */ + void* qudaCreateExtendedGaugeField(void* gauge, + int geometry, + int precision); + + /** + * Take the QUDA resident gauge field and extend it. + * Return a pointer to the extended gauge field object. + * + * @param gauge The CPU gauge field (optional - if set to 0 then the gauge field zeroed) + * @param geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param precision The precision of the fields (2 - double, 1 - single) + * @return Pointer to the gauge field (cast as a void*) + */ + void* qudaResidentExtendedGaugeField(void* gauge, + int geometry, + int precision); + + /** + * Allocate a gauge (matrix) field on the device and optionally download a host gauge field. + * + * @param gauge The host gauge field (optional - if set to 0 then the gauge field zeroed) + * @param geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param precision The precision of the field to be created (2 - double, 1 - single) + * @return Pointer to the gauge field (cast as a void*) + */ + void* qudaCreateGaugeField(void* gauge, + int geometry, + int precision); + + /** + * Copy the QUDA gauge (matrix) field on the device to the CPU + * + * @param outGauge Pointer to the host gauge field + * @param inGauge Pointer to the device gauge field (QUDA device field) + */ + void qudaSaveGaugeField(void* gauge, + void* inGauge); + + /** + * Reinterpret gauge as a pointer to cudaGaugeField and call destructor. + * + * @param gauge Gauge field to be freed + */ void qudaDestroyGaugeField(void* gauge); - + #ifdef __cplusplus } #endif