From 4ed06166ff0764f1396b40d81b39e4790a5e35fb Mon Sep 17 00:00:00 2001 From: lhausamm <loic_hausammann@hotmail.com> Date: Fri, 8 Dec 2017 11:26:09 +0100 Subject: [PATCH] Write doxygen documentation --- src/cooling_wrapper.h | 22 +++++++++++++++++++++ src/parser_wrapper.h | 9 +++++++++ src/part_wrapper.h | 9 +++++++++ src/pyswiftsim_tools.c | 25 +++++++++++++++++++----- src/pyswiftsim_tools.h | 44 +++++++++++++++++++++++++++++++++++++++++- src/units_wrapper.h | 18 +++++++++++++++++ src/wrapper.c | 2 ++ 7 files changed, 123 insertions(+), 6 deletions(-) diff --git a/src/cooling_wrapper.h b/src/cooling_wrapper.h index 95717e8..4fbdd8a 100644 --- a/src/cooling_wrapper.h +++ b/src/cooling_wrapper.h @@ -3,8 +3,30 @@ #include "pyswiftsim_tools.h" +/** + * @brief Initialize the cooling + * + * args is expecting pyswiftsim classes in the following order: + * SwiftParams, UnitSystem and PhysConst. + * + * @param self calling object + * @param args arguments + * @return CoolingFunctionData + */ PyObject* pycooling_init(PyObject* self, PyObject* args); +/** + * @brief Compute cooling rate + * + * args is expecting pyswiftsim classes in the following order: + * PhysConst, UnitSystem and CoolingFunctionData. + * Then two numpy arrays (density and specific energy) and an optional + * float for the time step + * + * @param self calling object + * @param args arguments + * @return cooling rate + */ PyArrayObject* pycooling_rate(PyObject* self, PyObject* args); #endif // __PYSWIFTSIM_COOLING_H__ diff --git a/src/parser_wrapper.h b/src/parser_wrapper.h index b94ca16..529d352 100644 --- a/src/parser_wrapper.h +++ b/src/parser_wrapper.h @@ -3,6 +3,15 @@ #include <Python.h> +/** + * @brief Read swift parameters + * + * args is expecting a string. + * + * @param self calling object + * @param args arguments + * @return SwiftParams + */ PyObject* pyparser_read_file(PyObject *self, PyObject *args); diff --git a/src/part_wrapper.h b/src/part_wrapper.h index 9f34c85..58a426f 100644 --- a/src/part_wrapper.h +++ b/src/part_wrapper.h @@ -4,6 +4,15 @@ #include <Python.h> #include <part.h> +/** + * @brief Test function for the struct + * + * args is expecting no argument. + * + * @param self calling object + * @param args arguments + * @return Part + */ PyObject* pypart_test_struct(PyObject *self, PyObject *args); #endif // __PYSWIFTSIM_PART_H__ diff --git a/src/pyswiftsim_tools.c b/src/pyswiftsim_tools.c index 3cbad7f..07ba933 100644 --- a/src/pyswiftsim_tools.c +++ b/src/pyswiftsim_tools.c @@ -71,12 +71,15 @@ PyObject* pytools_return(void *p, int class) char module_name[STRING_SIZE] = "pyswiftsim.structure"; char *class_pyname; + /* check class */ if (class >= class_count) pyerror("Class %i does not exists", class); + /* get class information */ nber_bytes = class_size[class]; class_pyname = class_name[class]; + /* import python class */ python_class = pytools_import(module_name, class_pyname); if (python_class == NULL) @@ -104,13 +107,15 @@ PyObject* pytools_return(void *p, int class) char* pytools_get_type_name(PyObject *obj) { + /* get object type */ PyObject *type = PyObject_Type(obj); if (type == NULL) { Py_DECREF(type); pyerror("Unable to get type"); } - + + /* get object name */ PyObject* recv = PyObject_Str(type); Py_DECREF(type); @@ -119,7 +124,8 @@ char* pytools_get_type_name(PyObject *obj) Py_DECREF(recv); pyerror("Unable to get string representation"); } - + + /* transform to C */ size_t size; char *name = PyUnicode_AsUTF8AndSize(recv, size); Py_DECREF(recv); @@ -138,13 +144,17 @@ char* pytools_construct(PyObject* obj, int class) char *module_name = "pyswiftsim.structure"; char *class_pyname; + /* check python class */ if (class >= class_count) pyerror("Class %i does not exists", class); + /* get class information */ class_pyname = class_name[class]; + /* import class */ PyObject *pyclass = pytools_import(module_name, class_pyname); + /* check if classes correspond */ int test = !PyObject_IsInstance(obj, pyclass); Py_DECREF(pyclass); if (test) @@ -155,7 +165,8 @@ char* pytools_construct(PyObject* obj, int class) pyerror("Expecting class %s, received %s", class_pyname, recv); } - + + /* copy python class' data to C */ PyObject* data = PyObject_GetAttrString(obj, "data"); if (data == NULL) @@ -170,18 +181,22 @@ char* pytools_construct(PyObject* obj, int class) int pytools_check_array(PyArrayObject *obj, int dim, int type) { + /* ensure to have numpy arrays */ IMPORT_ARRAY(); - + + /* check if array */ if (!PyArray_Check(obj)) { pyerror("Expecting a numpy array"); } - + + /* check if required dim */ if (PyArray_NDIM(obj) != dim) { pyerror("Array should be a %i dimensional object", dim); } + /* check data type */ if (PyArray_TYPE(obj) != type) { pyerror("Wrong array type"); diff --git a/src/pyswiftsim_tools.h b/src/pyswiftsim_tools.h index 75f2737..9d03af9 100644 --- a/src/pyswiftsim_tools.h +++ b/src/pyswiftsim_tools.h @@ -29,6 +29,7 @@ return FAIL; \ }) +/* debugging function */ #define pydebug(s, ...) \ ({ \ PyErr_Print(); \ @@ -36,7 +37,8 @@ __FUNCTION__, __LINE__, ##__VA_ARGS__); \ }) -enum class { +/* Enum swift classes */ +enum swift_class { class_unit_system, class_part, class_swift_params, @@ -45,21 +47,61 @@ enum class { class_count /* should always be last! */ }; +/* size of each structure in enum swift_class */ extern const size_t class_size[]; +/* name of each Python class representing a swift class */ extern const char *class_name[]; +/* error code in pyswiftsim */ enum error_code { FAIL = 0, // ensure NULL == FAIL SUCCESS, }; + +/** + * @brief Construct a python object from a C struct + * + * @param p pointer to the C struct + * @param class #swift_class of the pointer + * @return PyObject of the required class + */ PyObject* pytools_return(void* p, int class); +/** + * @brief Construct a C struct from a python object + * + * @param obj pointer to the python object + * @param class #swift_class of the pointer + * @return pointer to the required struct + */ char* pytools_construct(PyObject* obj, int class); +/** + * @brief Import a python library/function + * + * @param module Module name + * @param object_name object to import from module + * @return (PyObject) imported object + */ PyObject* pytools_import(char* module, char* object_name); +/** + * @brief get type name in C + * + * @param obj PyObject from which to get the name0 + * @return type name + */ char* pytools_get_type_name(PyObject *obj); +/** + * @brief Check if object is the expected PyArray type + * + * @param obj PyArray to check + * @param dim required dimension + * @param int required type + * @return #error_code result of the test + */ int pytools_check_array(PyArrayObject *obj, int dim, int type); + #endif // __PYSWIFTSIM_TOOLS_H__ diff --git a/src/units_wrapper.h b/src/units_wrapper.h index 0d5d6ff..867e055 100644 --- a/src/units_wrapper.h +++ b/src/units_wrapper.h @@ -3,8 +3,26 @@ #include <Python.h> +/** + * @brief Test function for the struct + * + * args is expecting no argument. + * + * @param self calling object + * @param args arguments + * @return UnitSystem + */ PyObject* pyunit_system_test_struct(PyObject *self, PyObject *args); +/** + * @brief Initialize the unit system + * + * args is expecting a pyswift SwiftParms object. + * + * @param self calling object + * @param args arguments + * @return UnitSystem + */ PyObject* pyunit_system_init(PyObject *self, PyObject *args); #endif // __PYSWIFTSIM_UNITS_H__ diff --git a/src/wrapper.c b/src/wrapper.c index 58f8fff..27fc591 100644 --- a/src/wrapper.c +++ b/src/wrapper.c @@ -54,7 +54,9 @@ PyMODINIT_FUNC PyInit_wrapper(void) { PyObject *m; + /* set time for swift */ clocks_set_cpufreq(0); + import_array(); Py_Initialize(); m = PyModule_Create(&wrapper_cmodule); -- GitLab