From e0451efdc6690281a9d463c2135c00128d7c88a8 Mon Sep 17 00:00:00 2001 From: alexstrel Date: Wed, 24 Apr 2024 14:42:59 -0500 Subject: [PATCH] updated (corrected) doxygen comments for milc interface functions --- include/quda_milc_interface.h | 570 +++++++++++++++++----------------- 1 file changed, 285 insertions(+), 285 deletions(-) diff --git a/include/quda_milc_interface.h b/include/quda_milc_interface.h index 0331d7289a..3583cedbbf 100644 --- a/include/quda_milc_interface.h +++ b/include/quda_milc_interface.h @@ -146,21 +146,21 @@ extern "C" { /** * Optional: Set the MPI Comm Handle if it is not MPI_COMM_WORLD * - * @param input Pointer to an MPI_Comm handle, static cast as a void * + * @param[in] input Pointer to an MPI_Comm handle, static cast as a void * */ void qudaSetMPICommHandle(void *mycomm); /** * Initialize the QUDA context. * - * @param input Meta data for the QUDA context + * @param[in] input Meta data for the QUDA context */ void qudaInit(QudaInitArgs_t input); /** * Set set the local dimensions and machine topology for QUDA to use * - * @param layout Struct defining local dimensions and machine topology + * @param[in] layout Struct defining local dimensions and machine topology */ void qudaSetLayout(QudaLayout_t layout); @@ -171,27 +171,27 @@ extern "C" { /** * Allocate pinned memory suitable for CPU-GPU transfers - * @param bytes The size of the requested allocation + * @param[in] bytes The size of the requested allocation * @return Pointer to allocated memory */ void* qudaAllocatePinned(size_t bytes); /** * Free pinned memory - * @param ptr Pointer to memory to be free + * @param[in] ptr Pointer to memory to be free */ void qudaFreePinned(void *ptr); /** * Allocate managed memory to reduce CPU-GPU transfers - * @param bytes The size of the requested allocation + * @param[in] bytes The size of the requested allocation * @return Pointer to allocated memory */ void *qudaAllocateManaged(size_t bytes); /** * Free managed memory - * @param ptr Pointer to memory to be free + * @param[in] ptr Pointer to memory to be free */ void qudaFreeManaged(void *ptr); @@ -199,7 +199,7 @@ extern "C" { * Set the algorithms to use for HISQ fermion calculations, e.g., * SVD parameters for reunitarization. * - * @param hisq_params Meta data desribing the algorithms to use for HISQ fermions + * @param[in] hisq_params Meta data desribing the algorithms to use for HISQ fermions */ void qudaHisqParamsInit(QudaHisqParams_t hisq_params); @@ -208,12 +208,12 @@ extern "C" { * fields passed here are host fields, that must be preallocated. * The precision of all fields must match. * - * @param precision The precision of the fields - * @param fatlink_args Meta data for the algorithms to deploy - * @param act_path_coeff Array of coefficients for each path in the action - * @param inlink Host gauge field used for input - * @param fatlink Host fat-link field that is computed - * @param longlink Host long-link field that is computed + * @param[in] precision The precision of the fields + * @param[in] fatlink_args Meta data for the algorithms to deploy + * @param[in] act_path_coeff Array of coefficients for each path in the action + * @param[in] inlink Host gauge field used for input + * @param[out] fatlink Host fat-link field that is computed + * @param[out] longlink Host long-link field that is computed */ void qudaLoadKSLink(int precision, QudaFatLinkArgs_t fatlink_args, @@ -227,12 +227,12 @@ extern "C" { * All fields passed here are host fields, that must be * preallocated. The precision of all fields must match. * - * @param precision The precision of the fields - * @param fatlink_args Meta data for the algorithms to deploy - * @param path_coeff Array of coefficients for each path in the action - * @param inlink Host gauge field used for input - * @param fatlink Host fat-link field that is computed - * @param ulink Host unitarized field that is computed + * @param[in] precision The precision of the fields + * @param[in] fatlink_args Meta data for the algorithms to deploy + * @param[in] path_coeff Array of coefficients for each path in the action + * @param[in] inlink Host gauge field used for input + * @param[out] fatlink Host fat-link field that is computed + * @param[out] ulink Host unitarized field that is computed */ void qudaLoadUnitarizedLink(int precision, QudaFatLinkArgs_t fatlink_args, @@ -246,14 +246,14 @@ extern "C" { * Apply the forward/backward/symmetric shift for the spin-taste opeartor. All fields * passed and returned are host (CPU) field in MILC order. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param links Gauge field on the host - * @param src Input spinor field - * @param dst Output spinor field - * @param dir Direction of application of the spin-taste operator - * @param sym Kind of spin-taste operator (1 forward, 2 backward, 3 symmetric) - * @param reloadGaugeField Should we transfer again the gauge field from the CPU to the GPU? (0 = false, anything else = true) + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] links Gauge field on the host + * @param[in] src Input spinor field + * @param[out] dst Output spinor field + * @param[in] dir Direction of application of the spin-taste operator + * @param[in] sym Kind of spin-taste operator (1 forward, 2 backward, 3 symmetric) + * @param[in] reloadGaugeField Should we transfer again the gauge field from the CPU to the GPU? (0 = false, anything else = true) */ void qudaShift (int external_precision, int quda_precision, @@ -268,14 +268,14 @@ extern "C" { * Apply the forward/backward/symmetric shift for the spin-taste opeartor. All fields * passed and returned are host (CPU) field in MILC order. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param links Gauge field on the host - * @param src Input spinor field - * @param dst Output spinor field - * @param spin Spin gamma structure using MILC numbering - * @param taste Taste gamma structure using MILC numbering - * @param reloadGaugeField Should we transfer again the gauge field from the CPU to the GPU? (0 = false, anything else = true) + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] links Gauge field on the host + * @param[in] src Input spinor field + * @param[out] dst Output spinor field + * @param[in] spin Spin gamma structure using MILC numbering + * @param[in] taste Taste gamma structure using MILC numbering + * @param[in] reloadGaugeField Should we transfer again the gauge field from the CPU to the GPU? (0 = false, anything else = true) */ void qudaSpinTaste (int external_precision, int quda_precision, @@ -289,13 +289,13 @@ extern "C" { * Apply the improved staggered operator to a field. All fields * passed and returned are host (CPU) field in MILC order. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param inv_args Struct setting some solver metadata - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param source Right-hand side source field - * @param solution Solution spinor field + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] inv_args Struct setting some solver metadata + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field */ void qudaDslash(int external_precision, int quda_precision, @@ -313,20 +313,20 @@ extern "C" { * function requires that persistent gauge and clover fields have * been created prior. This interface is experimental. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param precision Precision for QUDA to use (2 - double, 1 - single) - * @param mass Fermion mass parameter - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param target_relative_residual Target Fermilab residual - * @param domain_overlap Array specifying the overlap of the domains in each dimension - * @param fatlink Fat-link field on the host - * @param longlink Long-link field on the host - * @param source Right-hand side source field - * @param solution Solution spinor field - * @param final_residual True residual - * @param final_relative_residual True Fermilab residual - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] mass Fermion mass parameter + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] target_relative_residual Target Fermilab residual + * @param[in] domain_overlap Array specifying the overlap of the domains in each dimension + * @param[in] fatlink Fat-link field on the host + * @param[in] longlink Long-link field on the host + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field + * @param[in] final_residual True residual + * @param[in] final_relative_residual True Fermilab residual + * @param[in] num_iters Number of iterations taken */ void qudaDDInvert(int external_precision, int quda_precision, @@ -351,19 +351,19 @@ extern "C" { * function requires that persistent gauge and clover fields have * been created prior. This interface is experimental. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param mass Fermion mass parameter - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param target_relative_residual Target Fermilab residual - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param source Right-hand side source field - * @param solution Solution spinor field - * @param final_residual True residual - * @param final_relative_residual True Fermilab residual - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] mass Fermion mass parameter + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] target_relative_residual Target Fermilab residual + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field + * @param[in] final_residual True residual + * @param[in] final_relative_residual True Fermilab residual + * @param[in] num_iters Number of iterations taken */ void qudaInvert(int external_precision, int quda_precision, @@ -385,13 +385,13 @@ extern "C" { * in MILC order. This function requires persistent gauge fields. * This interface is experimental. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param mass Fermion mass parameter - * @param inv_args Struct setting some solver metadata; required for tadpole, naik coeff - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param mg_param_file Path to an input text file describing the MG solve, to be documented on QUDA wiki + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] mass Fermion mass parameter + * @param[in] inv_args Struct setting some solver metadata; required for tadpole, naik coeff + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] mg_param_file Path to an input text file describing the MG solve, to be documented on QUDA wiki * @return Void pointer wrapping a pack of multigrid-related structures */ void *qudaMultigridCreate(int external_precision, int quda_precision, double mass, QudaInvertArgs_t inv_args, @@ -406,21 +406,21 @@ extern "C" { * requires a multigrid parameter built from qudaSetupMultigrid * This interface is experimental. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param mass Fermion mass parameter - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param target_relative_residual Target Fermilab residual - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param mg_pack_ptr MG preconditioner structure created by qudaSetupMultigrid - * @param mg_rebuild_type whether to do a full (1) or thin (0) MG rebuild - * @param source Right-hand side source field - * @param solution Solution spinor field - * @param final_residual True residual - * @param final_relative_residual True Fermilab residual - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] mass Fermion mass parameter + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] target_relative_residual Target Fermilab residual + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] mg_pack_ptr MG preconditioner structure created by qudaSetupMultigrid + * @param[in] mg_rebuild_type whether to do a full (1) or thin (0) MG rebuild + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field + * @param[in] final_residual True residual + * @param[in] final_relative_residual True Fermilab residual + * @param[in] num_iters Number of iterations taken */ void qudaInvertMG(int external_precision, int quda_precision, double mass, QudaInvertArgs_t inv_args, double target_residual, double target_fermilab_residual, const void *const milc_fatlink, @@ -431,7 +431,7 @@ extern "C" { * Clean up a staggered/HISQ multigrid object, freeing all internal * fields and otherwise allocated memory. * - * @param mg_pack_ptr Void pointer mapping to the multigrid structure returned by qudaSetupMultigrid + * @param[in] mg_pack_ptr Void pointer mapping to the multigrid structure returned by qudaSetupMultigrid */ void qudaMultigridDestroy(void *mg_pack_ptr); @@ -441,20 +441,20 @@ extern "C" { * This function requires that persistent gauge and clover fields have * been created prior. This interface is experimental. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param mass Fermion mass parameter - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param target_relative_residual Target Fermilab residual - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param source array of right-hand side source fields - * @param solution array of solution spinor fields - * @param final_residual True residual - * @param final_relative_residual True Fermilab residual - * @param num_iters Number of iterations taken - * @param num_src Number of source fields + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] mass Fermion mass parameter + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] target_relative_residual Target Fermilab residual + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] source array of right-hand side source fields + * @param[out] solution array of solution spinor fields + * @param[in] final_residual True residual + * @param[in] final_relative_residual True Fermilab residual + * @param[in] num_iters Number of iterations taken + * @param[in] num_src Number of source fields */ void qudaInvertMsrc(int external_precision, int quda_precision, @@ -480,20 +480,20 @@ extern "C" { * are used, else reliable updates are used with a reliable_delta * parameter of 0.1. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param precision Precision for QUDA to use (2 - double, 1 - single) - * @param num_offsets Number of shifts to solve for - * @param offset Array of shift offset values - * @param inv_args Struct setting some solver metadata - * @param target_residual Array of target residuals per shift - * @param target_relative_residual Array of target Fermilab residuals per shift - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param source Right-hand side source field - * @param solutionArray Array of solution spinor fields - * @param final_residual Array of true residuals - * @param final_relative_residual Array of true Fermilab residuals - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] num_offsets Number of shifts to solve for + * @param[in] offset Array of shift offset values + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Array of target residuals per shift + * @param[in] target_relative_residual Array of target Fermilab residuals per shift + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] source Right-hand side source field + * @param[out] solutionArray Array of solution spinor fields + * @param[in] final_residual Array of true residuals + * @param[in] final_relative_residual Array of true Fermilab residuals + * @param[in] num_iters Number of iterations taken */ void qudaMultishiftInvert( int external_precision, @@ -521,23 +521,23 @@ extern "C" { * are host (CPU) field in MILC order. This function requires that * persistent gauge and clover fields have been created prior. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param precision Precision for QUDA to use (2 - double, 1 - single) - * @param num_offsets Number of shifts to solve for - * @param offset Array of shift offset values - * @param inv_args Struct setting some solver metadata - * @param target_residual Array of target residuals per shift - * @param target_relative_residual Array of target Fermilab residuals per shift - * @param milc_fatlink Fat-link field on the host - * @param milc_longlink Long-link field on the host - * @param source Right-hand side source field - * @param solution Array of solution spinor fields - * @param eig_args contains info about deflation space - * @param rhs_idx bookkeep current rhs - * @param last_rhs_flag is this the last rhs to solve? - * @param final_residual Array of true residuals - * @param final_relative_residual Array of true Fermilab residuals - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] num_offsets Number of shifts to solve for + * @param[in] offset Array of shift offset values + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Array of target residuals per shift + * @param[in] target_relative_residual Array of target Fermilab residuals per shift + * @param[in] milc_fatlink Fat-link field on the host + * @param[in] milc_longlink Long-link field on the host + * @param[in] source Right-hand side source field + * @param[out] solution Array of solution spinor fields + * @param[in] eig_args contains info about deflation space + * @param[in] rhs_idx bookkeep current rhs + * @param[in] last_rhs_flag is this the last rhs to solve? + * @param[in] final_residual Array of true residuals + * @param[in] final_relative_residual Array of true Fermilab residuals + * @param[in] num_iters Number of iterations taken */ void qudaEigCGInvert( int external_precision, @@ -563,21 +563,21 @@ extern "C" { * function creates the gauge and clover field from the host fields. * Reliable updates are used with a reliable_delta parameter of 0.1. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param kappa Kappa value - * @param clover_coeff Clover coefficient - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param milc_link Gauge field on the host - * @param milc_clover Clover field on the host - * @param milc_clover_inv Inverse clover on the host - * @param clover_coeff Clover coefficient - * @param source Right-hand side source field - * @param solution Solution spinor field - * @param final_residual True residual returned by the solver - * @param final_residual True Fermilab residual returned by the solver - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] kappa Kappa value + * @param[in] clover_coeff Clover coefficient + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] milc_link Gauge field on the host + * @param[in] milc_clover Clover field on the host + * @param[in] milc_clover_inv Inverse clover on the host + * @param[in] clover_coeff Clover coefficient + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field + * @param[in] final_residual True residual returned by the solver + * @param[in] final_residual True Fermilab residual returned by the solver + * @param[in] num_iters Number of iterations taken */ void qudaCloverInvert(int external_precision, int quda_precision, @@ -604,24 +604,24 @@ extern "C" { * are host (CPU) field in MILC order. This function requires that * persistent gauge and clover fields have been created prior. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param kappa Kappa value - * @param clover_coeff Clover coefficient - * @param inv_args Struct setting some solver metadata - * @param target_residual Target residual - * @param milc_link Gauge field on the host - * @param milc_clover Clover field on the host - * @param milc_clover_inv Inverse clover on the host - * @param clover_coeff Clover coefficient - * @param source Right-hand side source field - * @param solution Solution spinor field - * @param eig_args contains info about deflation space - * @param rhs_idx bookkeep current rhs - * @param last_rhs_flag is this the last rhs to solve? - * @param final_residual Array of true residuals - * @param final_relative_residual Array of true Fermilab residuals - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] kappa Kappa value + * @param[in] clover_coeff Clover coefficient + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Target residual + * @param[in] milc_link Gauge field on the host + * @param[in] milc_clover Clover field on the host + * @param[in] milc_clover_inv Inverse clover on the host + * @param[in] clover_coeff Clover coefficient + * @param[in] source Right-hand side source field + * @param[out] solution Solution spinor field + * @param[in] eig_args contains info about deflation space + * @param[in] rhs_idx bookkeep current rhs + * @param[in] last_rhs_flag is this the last rhs to solve? + * @param[in] final_residual Array of true residuals + * @param[in] final_relative_residual Array of true Fermilab residuals + * @param[in] num_iters Number of iterations taken */ void qudaEigCGCloverInvert( int external_precision, @@ -647,10 +647,10 @@ extern "C" { /** * Load the gauge field from the host. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param inv_args Meta data - * @param milc_link Base pointer to host gauge field (regardless of dimensionality) + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] inv_args Meta data + * @param[in] milc_link Base pointer to host gauge field (regardless of dimensionality) */ void qudaLoadGaugeField(int external_precision, int quda_precision, @@ -673,18 +673,18 @@ extern "C" { * pointers are passed, the clover field and / or its inverse will * be computed dynamically from the resident gauge field. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param inv_args Meta data - * @param milc_clover Pointer to host clover field. If 0 then the + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] inv_args Meta data + * @param[in] milc_clover Pointer to host clover field. If 0 then the * clover field is computed dynamically within QUDA. - * @param milc_clover_inv Pointer to host inverse clover field. If + * @param[in] milc_clover_inv Pointer to host inverse clover field. If * 0 then the inverse if computed dynamically within QUDA. - * @param solution_type The type of solution required (mat, matpc) - * @param solve_type The solve type to use (normal/direct/preconditioning) - * @param clover_coeff Clover coefficient - * @param compute_trlog Whether to compute the trlog of the clover field when inverting - * @param Array for storing the trlog (length two, one for each parity) + * @param[in] solution_type The type of solution required (mat, matpc) + * @param[in] solve_type The solve type to use (normal/direct/preconditioning) + * @param[in] clover_coeff Clover coefficient + * @param[in] compute_trlog Whether to compute the trlog of the clover field when inverting + * @param[in] Array for storing the trlog (length two, one for each parity) */ void qudaLoadCloverField(int external_precision, int quda_precision, @@ -711,19 +711,19 @@ extern "C" { * no reliable updates are used, else reliable updates are used with * a reliable_delta parameter of 0.1. * - * @param external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) - * @param quda_precision Precision for QUDA to use (2 - double, 1 - single) - * @param num_offsets Number of shifts to solve for - * @param offset Array of shift offset values - * @param kappa Kappa value - * @param clover_coeff Clover coefficient - * @param inv_args Struct setting some solver metadata - * @param target_residual Array of target residuals per shift - * @param clover_coeff Clover coefficient - * @param source Right-hand side source field - * @param solutionArray Array of solution spinor fields - * @param final_residual Array of true residuals - * @param num_iters Number of iterations taken + * @param[in] external_precision Precision of host fields passed to QUDA (2 - double, 1 - single) + * @param[in] quda_precision Precision for QUDA to use (2 - double, 1 - single) + * @param[in] num_offsets Number of shifts to solve for + * @param[in] offset Array of shift offset values + * @param[in] kappa Kappa value + * @param[in] clover_coeff Clover coefficient + * @param[in] inv_args Struct setting some solver metadata + * @param[in] target_residual Array of target residuals per shift + * @param[in] clover_coeff Clover coefficient + * @param[in] source Right-hand side source field + * @param[out] solutionArray Array of solution spinor fields + * @param[in] final_residual Array of true residuals + * @param[in] num_iters Number of iterations taken */ void qudaCloverMultishiftInvert(int external_precision, int quda_precision, @@ -744,18 +744,18 @@ extern "C" { * are host fields in MILC order, and the precision of these fields * must match. * - * @param precision The precision of the fields - * @param num_terms The number of quark fields - * @param num_naik_terms The number of naik contributions - * @param dt Integrating step size - * @param coeff The coefficients multiplying the fermion fields in the outer product - * @param quark_field The input fermion field. - * @param level2_coeff The coefficients for the second level of smearing in the quark action. - * @param fat7_coeff The coefficients for the first level of smearing (fat7) in the quark action. - * @param w_link Unitarized link variables obtained by applying fat7 smearing and unitarization to the original links. - * @param v_link Fat7 link variables. - * @param u_link SU(3) think link variables. - * @param milc_momentum The momentum contribution from the quark action. + * @param[in] precision The precision of the fields + * @param[in] num_terms The number of quark fields + * @param[in] num_naik_terms The number of naik contributions + * @param[in] dt Integrating step size + * @param[in] coeff The coefficients multiplying the fermion fields in the outer product + * @param[in] quark_field The input fermion field. + * @param[in] level2_coeff The coefficients for the second level of smearing in the quark action. + * @param[in] fat7_coeff The coefficients for the first level of smearing (fat7) in the quark action. + * @param[in] w_link Unitarized link variables obtained by applying fat7 smearing and unitarization to the original links. + * @param[in] v_link Fat7 link variables. + * @param[in] u_link SU(3) think link variables. + * @param[in] milc_momentum The momentum contribution from the quark action. */ void qudaHisqForce(int precision, int num_terms, @@ -775,11 +775,11 @@ extern "C" { * here are CPU fields in MILC order, and their precisions should * match. * - * @param precision The precision of the field (2 - double, 1 - single) - * @param num_loop_types 1, 2 or 3 - * @param milc_loop_coeff Coefficients of the different loops in the Symanzik action - * @param eb3 The integration step size (for MILC this is dt*beta/3) - * @param arg Metadata for MILC's internal site struct array + * @param[in] precision The precision of the field (2 - double, 1 - single) + * @param[in] num_loop_types 1, 2 or 3 + * @param[in] milc_loop_coeff Coefficients of the different loops in the Symanzik action + * @param[in] eb3 The integration step size (for MILC this is dt*beta/3) + * @param[in] arg Metadata for MILC's internal site struct array */ void qudaGaugeForce(int precision, int num_loop_types, @@ -792,12 +792,12 @@ extern "C" { * here are CPU fields in MILC order, and their precisions should * match. * - * @param precision The precision of the field (2 - double, 1 - single) - * @param num_loop_types 1, 2 or 3 - * @param milc_loop_coeff Coefficients of the different loops in the Symanzik action - * @param eb3 The integration step size (for MILC this is dt*beta/3) - * @param arg Metadata for MILC's internal site struct array - * @param phase_in whether staggered phases are applied + * @param[in] precision The precision of the field (2 - double, 1 - single) + * @param[in] num_loop_types 1, 2 or 3 + * @param[in] milc_loop_coeff Coefficients of the different loops in the Symanzik action + * @param[in] eb3 The integration step size (for MILC this is dt*beta/3) + * @param[in] arg Metadata for MILC's internal site struct array + * @param[in] phase_in whether staggered phases are applied */ void qudaGaugeForcePhased(int precision, int num_loop_types, double milc_loop_coeff[3], double eb3, QudaMILCSiteArg_t *arg, int phase_in); @@ -871,9 +871,9 @@ extern "C" { * 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 arg Metadata for MILC's internal site struct array + * @param[in] precision Precision of the field (2 - double, 1 - single) + * @param[in] dt The integration step size step + * @param[in] arg Metadata for MILC's internal site struct array */ void qudaUpdateU(int precision, double eps, @@ -883,10 +883,10 @@ extern "C" { * 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 arg Metadata for MILC's internal site struct array - * @param phase_in whether staggered phases are applied + * @param[in] precision Precision of the field (2 - double, 1 - single) + * @param[in] dt The integration step size step + * @param[in] arg Metadata for MILC's internal site struct array + * @param[in] phase_in whether staggered phases are applied */ void qudaUpdateUPhased(int precision, double eps, QudaMILCSiteArg_t *arg, int phase_in); @@ -894,11 +894,11 @@ extern "C" { * 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 arg Metadata for MILC's internal site struct array - * @param phase_in whether staggered phases are applied - * @param want_gaugepipe whether to enabled QUDA gaugepipe for HMC + * @param[in] precision Precision of the field (2 - double, 1 - single) + * @param[in] dt The integration step size step + * @param[in] arg Metadata for MILC's internal site struct array + * @param[in] phase_in whether staggered phases are applied + * @param[in] want_gaugepipe whether to enabled QUDA gaugepipe for HMC */ void qudaUpdateUPhasedPipeline(int precision, double eps, QudaMILCSiteArg_t *arg, int phase_in, int want_gaugepipe); @@ -919,8 +919,8 @@ extern "C" { * struct (QUDA_MILC_SITE_GAUGE_ORDER) or as a separate field * (QUDA_MILC_GAUGE_ORDER). * - * @param precision Precision of the field (2 - double, 1 - single) - * @param arg Metadata for MILC's internal site struct array + * @param[in] precision Precision of the field (2 - double, 1 - single) + * @param[in] arg Metadata for MILC's internal site struct array */ void qudaMomSave(int precision, QudaMILCSiteArg_t *arg); @@ -929,8 +929,8 @@ extern "C" { * action. MILC convention is applied, subtracting 4.0 from each * momentum matrix to increase stability. * - * @param precision Precision of the field (2 - double, 1 - single) - * @param arg Metadata for MILC's internal site struct array + * @param[in] precision Precision of the field (2 - double, 1 - single) + * @param[in] arg Metadata for MILC's internal site struct array * @return momentum action */ double qudaMomAction(int precision, QudaMILCSiteArg_t *arg); @@ -941,10 +941,10 @@ extern "C" { * exp(imu/T) will be applied to the links in the temporal * direction. * - * @param prec Precision of the gauge field - * @param gauge_h The gauge field - * @param flag Whether to apply to remove the staggered phase - * @param i_mu Imaginary chemical potential + * @param[in] prec Precision of the gauge field + * @param[in/out] gauge_h The gauge field + * @param[in] flag Whether to apply to remove the staggered phase + * @param[in] i_mu Imaginary chemical potential */ void qudaRephase(int prec, void *gauge, int flag, double i_mu); @@ -952,9 +952,9 @@ extern "C" { * Project the input field on the SU(3) group. If the target * tolerance is not met, this routine will give a runtime error. * - * @param prec Precision of the gauge field - * @param tol The tolerance to which we iterate - * @param arg Metadata for MILC's internal site struct array + * @param[in] prec Precision of the gauge field + * @param[in] tol The tolerance to which we iterate + * @param[in] arg Metadata for MILC's internal site struct array */ void qudaUnitarizeSU3(int prec, double tol, QudaMILCSiteArg_t *arg); @@ -962,10 +962,10 @@ extern "C" { * Project the input field on the SU(3) group. If the target * tolerance is not met, this routine will give a runtime error. * - * @param prec Precision of the gauge field - * @param tol The tolerance to which we iterate - * @param arg Metadata for MILC's internal site struct array - * @param phase_in whether staggered phases are applied + * @param[in] prec Precision of the gauge field + * @param[in] tol The tolerance to which we iterate + * @param[in] arg Metadata for MILC's internal site struct array + * @param[in] phase_in whether staggered phases are applied */ void qudaUnitarizeSU3Phased(int prec, double tol, QudaMILCSiteArg_t *arg, int phase_in); @@ -974,18 +974,18 @@ extern "C" { * the array solution fields, and compute the resulting momentum * field. * - * @param mom Momentum matrix - * @param dt Integrating step size - * @param x Array of solution vectors - * @param p Array of intermediate vectors - * @param coeff Array of residues for each contribution - * @param kappa kappa parameter - * @param ck -clover_coefficient * kappa / 8 - * @param nvec Number of vectors - * @param multiplicity Number of fermions represented by this bilinear - * @param gauge Gauge Field - * @param precision Precision of the fields - * @param inv_args Struct setting some solver metadata + * @param[in] mom Momentum matrix + * @param[in] dt Integrating step size + * @param[out] x Array of solution vectors + * @param[in] p Array of intermediate vectors + * @param[in] coeff Array of residues for each contribution + * @param[in] kappa kappa parameter + * @param[in] ck -clover_coefficient * kappa / 8 + * @param[in] nvec Number of vectors + * @param[in] multiplicity Number of fermions represented by this bilinear + * @param[in] gauge Gauge Field + * @param[in] precision Precision of the fields + * @param[in] inv_args Struct setting some solver metadata */ void qudaCloverForce(void *mom, double dt, void **x, void **p, double *coeff, double kappa, double ck, int nvec, double multiplicity, void *gauge, int precision, @@ -997,10 +997,10 @@ extern "C" { * 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 + * @param[out] out Sigma trace field (QUDA device field, geometry = 1) + * @param[in] dummy (not used) + * @param[in] mu mu direction + * @param[in] nu nu direction */ void qudaCloverTrace(void* out, void* dummy, @@ -1013,15 +1013,15 @@ extern "C" { * 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 + * @param[out] out Clover derivative field (QUDA device field, geometry = 1) + * @param[in] gauge Gauge field (extended QUDA device field, gemoetry = 4) + * @param[in] oprod Matrix field (outer product) which is multiplied by the derivative + * @param[in] mu mu direction + * @param[in] nu nu direction + * @param[in] coeff Coefficient of the clover derviative (including stepsize and clover coefficient) + * @param[in] precision Precision of the fields (2 = double, 1 = single) + * @param[in] parity Parity for which we are computing + * @param[in] conjugate Whether to make the oprod field anti-hermitian prior to multiplication */ void qudaCloverDerivative(void* out, void* gauge, @@ -1038,9 +1038,9 @@ 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 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) + * @param[in] gauge The CPU gauge field (optional - if set to 0 then the gauge field zeroed) + * @param[in] geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param[in] precision The precision of the fields (2 - double, 1 - single) * @return Pointer to the gauge field (cast as a void*) */ void* qudaCreateExtendedGaugeField(void* gauge, @@ -1051,9 +1051,9 @@ extern "C" { * 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) + * @param[in] gauge The CPU gauge field (optional - if set to 0 then the gauge field zeroed) + * @param[in] geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param[in] precision The precision of the fields (2 - double, 1 - single) * @return Pointer to the gauge field (cast as a void*) */ void* qudaResidentExtendedGaugeField(void* gauge, @@ -1063,9 +1063,9 @@ extern "C" { /** * 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) + * @param[in] gauge The host gauge field (optional - if set to 0 then the gauge field zeroed) + * @param[in] geometry The geometry of the matrix field to create (1 - scaler, 4 - vector, 6 - tensor) + * @param[in] 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, @@ -1075,8 +1075,8 @@ extern "C" { /** * 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) + * @param[out] outGauge Pointer to the host gauge field + * @param[in] inGauge Pointer to the device gauge field (QUDA device field) */ void qudaSaveGaugeField(void* gauge, void* inGauge); @@ -1084,7 +1084,7 @@ extern "C" { /** * Reinterpret gauge as a pointer to a GaugeField and call destructor. * - * @param gauge Gauge field to be freed + * @param[in] gauge Gauge field to be freed */ void qudaDestroyGaugeField(void* gauge);