diff --git a/CMakeLists.txt b/CMakeLists.txt index 27ba07811f407be57c6867352afbb64e63dd0a60..58e67e079a0d20bf4f9c1fea3283ddb319d7a488 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -310,6 +310,8 @@ if (DOXYGEN_FOUND) set (DOXYGEN_PROJECT_NAME "Graph Framework") set (DOXYGEN_EXCLUDE ${CMAKE_CURRENT_SOURCE_DIR}/LLVM ${CMAKE_CURRENT_SOURCE_DIR}/build) set (DOXYGEN_GENERATE_TREEVIEW YES) + set (DOXYGEN_USE_MATHJAX YES) + set (DOXYGEN_IMAGE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/graph_docs) doxygen_add_docs (doc) endif () diff --git a/README.md b/README.md index 77bd1274d4b5bc51b6c368f68e71c416e3e1d25a..fb7d55674893c690bcb4b4f0fec61d23b2dbdffa 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,22 @@ -# graph_framework +# Quick Start Guide -Graph computation framework that supports auto differentiation. +**graph_framework**: A graph computation framework that supports auto +differentiation. It is designed to allow domain scientists to create cross +platform GPU accelerated code and embed those codes in existing legacy tools. -# Dependencies -This code makes use of the [NetCDF `C` library](https://www.unidata.ucar.edu/software/netcdf/). - -On Macs, this requires the latest install of XCode 16.3. - -# Compiling -To compile the code, first clone this repository. - -A `graph_framework` directory will be created. In this directory create -a `build` directory and navigate to it. - -``` -cd graph_framework -mkdir build -cd build -``` - -It's recommended that you use the `ccmake` to configure the build system. -From inside the build directory, run the `ccmake` command +## Documentation +[graph_framework-docs](https://ornl-fusion.github.io/graph_framework-docs) +Documentation for the graph_framework. +## Obtaining the Code +To get started clone this repository using the command. ``` -ccmake ../ +git clone https://github.com/ORNL-Fusion/graph_framework.git ``` -Initally, there will be no options. Press the `c` key to configure. -During this step, the LLVM software repo is cloned and configured. -This may take a while. Once configured, there will be several options. - -- On Linux systems, you may optionally use CUDA by toggling the `USE_CUDA` -option. -- On Mac systems, you may optionally use Metal by toggling the `USE_METAL` -option. - -__NOTE__: On Macs using the default system compiler, you will need to change -the `CMAKE_CXX_COMPILER` to `clang++`. To do this press the `t` to toggle -to the advanced options. - -Once all the options are configured press the 'c' key again and a -generate 'g' option will be available. Pressing the 'g' key will finish -generating the make file and close out `ccmake`. - -One the makefile is created. The code can be built using `make` or -optionally built in parallel using `make -j'_[number of parallel intances]_. - -__NOTE__: To many parallel instances can cause the LLVM build system to -hang so it is recommended to limit these to less than 20 depending on -the available memory. - -Unit tests can be run by the `make test` command. An example ray tracing -case can be found in `efit_example.sh` of the `graph_driver` directory. +## Compiling the Code +For instructions to build the code consult the +[build system](https://ornl-fusion.github.io/graph_framework-docs/build_system.html) +documentation. This framework uses a [cmake](https://cmake.org) based build +system and requires the [NetCDF-C](https://www.unidata.ucar.edu/software/netcdf/) +library. diff --git a/graph_benchmark/xrays_bench.cpp b/graph_benchmark/xrays_bench.cpp index ef6d0425131e60399a7ab6ebfd52fdd72a8aeb62..28e2df999828fc7812a99b26e6484163d5abb50f 100644 --- a/graph_benchmark/xrays_bench.cpp +++ b/graph_benchmark/xrays_bench.cpp @@ -38,10 +38,10 @@ void bench_runner() { const size_t batch = NUM_RAYS/threads.size(); const size_t extra = NUM_RAYS%threads.size(); - timeing::measure_diagnostic_threaded time_setup("Setup Time"); - timeing::measure_diagnostic_threaded time_init("Init Time"); - timeing::measure_diagnostic_threaded time_compile("Compile Time"); - timeing::measure_diagnostic_threaded time_steps("Time Steps"); + timing::measure_diagnostic_threaded time_setup("Setup Time"); + timing::measure_diagnostic_threaded time_init("Init Time"); + timing::measure_diagnostic_threaded time_compile("Compile Time"); + timing::measure_diagnostic_threaded time_steps("Time Steps"); for (size_t i = 0, ie = threads.size(); i < ie; i++) { threads[i] = std::thread([&time_setup, &time_init, &time_compile, &time_steps, batch, extra] (const size_t thread_number) -> void { diff --git a/graph_c_binding/graph_c_binding.cpp b/graph_c_binding/graph_c_binding.cpp index 9f006a2fc2543fd54523e1fb2e23484696c3b93b..77ee4ca50493078dd7078a2f7e5cfa7b0e9c4b72 100644 --- a/graph_c_binding/graph_c_binding.cpp +++ b/graph_c_binding/graph_c_binding.cpp @@ -1127,7 +1127,7 @@ extern "C" { /// /// @param[in] c The graph C context. /// @param[in] arg The left opperand. -/// @returns sin(arg) +/// @returns cos(arg) //------------------------------------------------------------------------------ graph_node graph_cos(STRUCT_TAG graph_c_context *c, graph_node arg) { diff --git a/graph_c_binding/graph_c_binding.h b/graph_c_binding/graph_c_binding.h index 6cfd25891c2fe223a97bc33ab02fb71d5977f937..3736ed61f6d49832b0b4067a2a4b4cb32a529e92 100644 --- a/graph_c_binding/graph_c_binding.h +++ b/graph_c_binding/graph_c_binding.h @@ -2,6 +2,111 @@ /// @file graph_c_binding.h /// @brief Header file for the c binding library. //------------------------------------------------------------------------------ +//------------------------------------------------------------------------------ +/// @page graph_c_binding Embedding in C code +/// @brief Documentation for linking into a C code base. +/// @tableofcontents +/// +/// @section graph_c_binding_into Introduction +/// This section assumes the reader is already familar with developing C codes. +/// The simplist method to link framework code into a C code is to create a C++ +/// function with @code extern "C" @endcode First create a header file +/// c_callable.h +/// @code +/// extern "C" { +/// void c_callable_function(); +/// } +/// @endcode +/// +/// Next create a source file c_callable.c and add the +/// framework. This example uses the equation of a line example from the +/// @ref tutorial_workflow "making workflows" turorial. +/// @code +/// // Include the necessary framework headers. +/// +/// extern "C" { +/// void c_callable_function() { +/// auto x = graph::variable(3, "x"); +/// +/// // Define explicit constant. +/// auto m = graph::constant (0.4); +/// // Define implicit constant. +/// const T b = 0.6; +/// +/// // Equation of a line +/// auto y = m*x + b; +/// +/// // Auto differentiation. +/// auto dydx = y->df(x); +/// +/// x->set({1.0, 2.0, 3.0}); +/// +/// // Create a workflow manager. +/// workflow::manager work(0); +/// work.add_item({ +/// graph::variable_cast(x) +/// }, { +/// y, dydx +/// }, {}, NULL, "my_first_kernel", 3); +/// work.compile(); +/// +/// work.run(); +/// work.print(0, {x, y, dydx}); +/// work.print(1, {x, y, dydx}); +/// work.print(2, {x, y, dydx}); +/// } +/// } +/// @endcode +/// +///
+/// @section graph_c_binding_interface C Binding Interface +/// An alternative is to use the @ref graph_c_binding.h "C Language interface". +/// The C binding interface can be enabled as one of the cmake +/// @ref build_system_user_options "conifgure options". As an example, we will +/// convert the @ref tutorial_workflow "making workflows" turorial to use the +/// C language bindings. +/// @code +/// #include +/// +/// void c_binding() { +/// const bool use_safe_math = 0; +/// struct graph_c_context *c_context = graph_construct_context(DOUBLE, use_safe_math); +/// graph_node x = graph_variable(c_context, 3, "x"); +/// +/// graph_node m = graph_constant(c_context, 0.4); +/// graph_node b = graph_constant(c_context, 0.6); +/// +/// graph_node y = graph_add(c_context, graph_mul(c_context, m, x), b); +/// graph_node dydx = graph_df(c_context, y, x); +/// +/// double temp[3]; +/// temp[0] = 1.0; +/// temp[1] = 2.0; +/// temp[2] = 3.0; +/// graoh_set_variable(c_context, x, temp); +/// +/// graph_set_device_number(c_context, 0); +/// graph_node inputs[1]; +/// inputs[0] = x; +/// graph_node outputs[2]; +/// outputs[0] = y; +/// outputs[1] = dydx; +/// graph_add_item(c_context, inputs, 1, outputs, 2, NULL, NULL, 0, NULL, +/// "x", 3); +/// graph_compile(c_context); +/// graph_run(c_context); +/// graph_node inputs2[3]; +/// inputs2[0] = x; +/// inputs2[1] = y; +/// inputs2[2] = dydx; +/// graph_print(c_context, 0, inputs2, 3); +/// graph_print(c_context, 1, inputs2, 3); +/// graph_print(c_context, 2, inputs2, 3); +/// +/// graph_destroy_context(c_context); +/// } +/// @endcode +//------------------------------------------------------------------------------ #ifndef graph_c_binding_h #define graph_c_binding_h @@ -10,6 +115,16 @@ #include #include +//------------------------------------------------------------------------------ +/// @def START_GPU +/// Starts a Cocoa auto release pool when using the metal backend. No opt +/// otherwise. +//------------------------------------------------------------------------------ +//------------------------------------------------------------------------------ +/// @def END_GPU +/// Ends a Cocoa auto release pool when using the metal backend. No opt +/// otherwise. +//------------------------------------------------------------------------------ #ifdef USE_METAL #define START_GPU @autoreleasepool { #define END_GPU } @@ -18,6 +133,10 @@ #define END_GPU #endif +//------------------------------------------------------------------------------ +/// @def STRUCT_TAG +/// C++ mode needs to tag a graph_c_context as a struct. +//------------------------------------------------------------------------------ #ifdef __cplusplus extern "C" { #define STRUCT_TAG diff --git a/graph_docs/ColdPlasma.png b/graph_docs/ColdPlasma.png new file mode 100644 index 0000000000000000000000000000000000000000..07976fda96ef41d0812880f6ccba22b541cc9e83 Binary files /dev/null and b/graph_docs/ColdPlasma.png differ diff --git a/graph_docs/Efit.png b/graph_docs/Efit.png new file mode 100755 index 0000000000000000000000000000000000000000..f604af7258f22a95a28f2dd7c49b651a0119341e Binary files /dev/null and b/graph_docs/Efit.png differ diff --git a/graph_docs/O-Mode.png b/graph_docs/O-Mode.png new file mode 100644 index 0000000000000000000000000000000000000000..b05f7580f3eb8f4c8596980cd24146d0568d2d7c Binary files /dev/null and b/graph_docs/O-Mode.png differ diff --git a/graph_docs/X-Mode.png b/graph_docs/X-Mode.png new file mode 100644 index 0000000000000000000000000000000000000000..4a4f1b79f7e446cbf5f9878e21bfbba8f02762f5 Binary files /dev/null and b/graph_docs/X-Mode.png differ diff --git a/graph_docs/bohm-gross.png b/graph_docs/bohm-gross.png new file mode 100644 index 0000000000000000000000000000000000000000..f15beaecca64d5bf4e6b32e261422868115242d5 Binary files /dev/null and b/graph_docs/bohm-gross.png differ diff --git a/graph_docs/code_structure.dox b/graph_docs/code_structure.dox new file mode 100644 index 0000000000000000000000000000000000000000..a4f9225d68b509cc2ea5668632d9919e583c0c22 --- /dev/null +++ b/graph_docs/code_structure.dox @@ -0,0 +1,27 @@ +/*! + * @page code_structure Code Structure + * @brief Architecture of the code base. + * @tableofcontents + * + * @section code_structure_intro Introduction + * This topic covers the structure of the framework and the structure of the RF + * Ray tracing code xrays. + * + * @section code_structure_framework Framework + * The namespaces of the graph framework are: + * * @ref graph The operation nodes. + * * @ref workflow The routines for executing graphs. + * * @ref jit Generic interface for Just-In-Time compiling of the graphs. + * * @ref backend Host side buffers and operations. + * * @ref gpu Device drivers for CPU and the GPU. + * * @ref timing Routines for timing. + * * @ref output Routines for loading and saving graph to Netcdf files. + * * @ref commandline Routines for parsing command lines. + * + * @section code_structure_xrays Ray Tracing code + * The namespaces of the Ray Tracing code are: + * * @ref equilibrium Equilibrium models. + * * @ref dispersion Dispersion functions. + * * @ref solver PDE integration methods and optimization methods. + * * @ref absorption The absorption models. + */ diff --git a/graph_docs/compiling.dox b/graph_docs/compiling.dox new file mode 100644 index 0000000000000000000000000000000000000000..36d8d4efb50c6cdb4dffdd4111068ecc2b4b38b4 --- /dev/null +++ b/graph_docs/compiling.dox @@ -0,0 +1,227 @@ +/*! + * @page build_system Build System + * @brief Overview of the Cmake based build system for the graph_framework. + * @tableofcontents + * + * @section build_system_introduction Introduction + * This page details the cmake based build + * system. + * + *
+ * @section build_system_user User Guide + * The following section is for users of the framework. + * + * @subsection build_system_user_dependencies Dependencies + * The graph_framwork requires three external dependencies and one optional + * dependency. LLVM is another dependency that is + * used for generating CPU code. However this is automatically obtained via the + * build system. The graph_frame is written using the + * C++20 standard. The + * C interface uses + * C17 + * and the fortran interface uses + * Fortran 2008. + * + * @subsubsection build_system_user_dependencies_required Required + * * cmake version greater than 3.21. + * * NetCDF-C library. + * * Python 3 environment. + * + * @subsubsection build_system_user_dependencies_optional Optional + * * Doxygen for generating this documentation. + * + * @subsection build_system_clone Obtaining the code + * The framework code itself can be obtained from the + * graph_framework + * Github repository. + * @code + git clone https://github.com/ORNL-Fusion/graph_framework.git + @endcode + * Source will be downloaded into a graph_framework directory + * unless a different directory is explicitly used. + * + * @subsection build_system_gen Generating the build system + * After the repository is cloned, create a build directory in the + * top level source directory and change into that directory. + * @code + mkdir build + cd build + @endcode + * There are two ways to run cmake. From the command line the build system can + * generated by using the cmake command with options set using the + * the -D option. As an exampole. + * @code + cmake -DOPTION_NAME=OPTION_VALUE ../ + @endcode + * Where ../ points to the source directory containing the top + * level CMakeLists.txt file. + * + * The recommended method is to use the interactive ccmake command + * instead. + * @code + ccmake ../ + @endcode + * Note options can still be set from the command line using the + * -D option. + * + * @subsubsection build_system_user_options Build system Options + * Initially, there will be no options. Along the botton, there are several + * commands. Use the 'c' command to start the configuation process. Once + * configured several options will apear. During this process cmake is cloning + * the LLVM repository. So this step may take some time initally. Most of the + * are various options for configuing LLVM and can be ignored. The important + * options are listed below. + * + * + * + *
Build options for users.
Option Discrption + *
CMAKE_BUILD_TYPE Switch between + * * Release + * * Debug + * * MinSizeRel + * * RelWithDebInfo + *
USE_VERBOSE Show verbose information about compute kernels. + *
BUILD_C_BINDING Generate the @ref graph_c_binding.h "C langauge interface". + *
BUILD_Fortran_BINDINGGenerate the @ref graph_fortran "Fortran language interface". + *
USE_METAL Enable the Metal backend (macOS only). + *
USE_CUDA Enable the Cuda backend (Linux only). + *
USE_HIP Enable the Hip backend (Linux only, Hip branch). + *
USE_SSH Use ssh for git instead of html. + *
+ * + * @note macOS users will need to change the default option for + * CMAKE_CXX_COMPILER to clang++. This is due to the way the + * build systems determines default include directories for system libraries. + * This can be accomplished using the advacned options accessed from the t + * command or setting this via the command line. + * @code + cmake -DCMAKE_CXX_COMPILER=clang++ ../ + @endcode + * + * Any time an option is changed, or a new option becomes is available, you need + * to use the configure c command for changes to take affect. Once all + * options are set, a generate g options will appear. Using this option + * will generate the Makefile. + * + * @subsubsection build_system_trouble_shooting Trouble Shooting. + * Some times, cmake will fail to locate the NetCDF library if it is not + * installed in a standard path. In these cases you can use the + * CMAKE_PREFIX_PATH to define the install location of the NetCDF + * library. For instance if the netcdf library is installed in + * /foo/bar/lib the prefix path should be set to /foo/bar. + * + * @subsection build_system_build Building the code. + * Once the build system is successfully generated a Makefile will appear. The + * code can be build using the + * @code + make + @endcode + * command. Note that the build system first starts by pulling the latest + * revision of LLVM. The build system then has to build LLVM first which can + * take a while. It is recommended to use a limited parallel build. + * @code + make -j10 + @endcode + * The -jnum_processes option determines number of parallel + * instances to run. The build products will be found in assocated directories + * in the build directory. + * + * A list of individual components which can be built can be identified using + * @code + make help + @endcode + * + * @subsection build_system_test Running unit tests + * Units tests can be run using the command. + * @code + make test ARGS=-j10 + @endcode + * Like the parallel build the -jnum_processes option determines + * the number of parallel instances to run. + * + *
+ * @section build_system_dev Developer Guide + * This section covers information for developers of the framework itself. + * + * @subsection build_system_macros Macro Definitions + * The build system defines some macros for defining targets, configuring debug + * options, and configuing external dependences. + * + * @subsubsection build_system_targets Tool targets + * + *
+ * add_tool_target(target lang)\n\n + * Define a tool target.\n\n + * Parameters\n + * [in] target The name of the target.\n + * [in] lang File extention for the target (c, cpp, f90).\n\n + * Target assumes there is a source file defined as target.lang. For + * instance a C++ source file named foo.cpp is configured as + * @code + add_tool_target(foo cpp) + @endcode + * This will generate a build target called xfoo. + * + *
+ * add_test_target(target lang)\n\n + * Define a test target.\n\n + * Parameters\n + * [in] target The name of the target.\n + * [in] lang File extention for the target (c, cpp, f90).\n\n + * The aguments are the same as add_tool_target. This also adds the + * target as a unit test. + *
+ * + * @subsubsection build_system_sanitizer Sanatizer flags + * + *
+ * register_sanitizer_option(name)\n\n + * Register a sanitizer option.\n\n + * Parameters\n + * [in] name The name of the sanitizer flags.\n\n + * This adds a new cmake option SANITIZE_NAME to add + * -fsanitize=name to the command line arguments. + *
+ * + * @subsubsection build_system_project Register an external project + * + *
+ * register_project(reg_name dir url default_tag sub_dir)\n\n + * Register an external project.\n\n + * Parameters\n + * [in] reg_name Name for the registered project.\n + * [in] dir Name directory to clone the project to.\n + * [in] url URL for the repository.\n + * [in] default_tag Default tag for to pull from.\n + * [in] sub_dir Subdirectory to locate the project source code.\n\n + * This function clones a external project into the directory defined by + * dir. This also adds a new build option for + * BUILD_TAG_DIR. The URL must have the format of + * @code + ${URL_PROTO}domain.com${URL_SEP}remining/url + @endcode + *
+ * + * @subsection build_system_debug Debugging + * In addition to the standard build options there are several debugging options + * that can be enabled. + * + * @subsubsection build_system_dev_options Build System Options + * + * + *
Build options for developers.
Option Discription + *
USE_PCH Use precompiled headers during computation. Most users should keep this on. + *
SAVE_KERNEL_SOURCE Option to dump the generated compute kernel source code to disk. + *
USE_INPUT_CACHE Option to cache registers for the kernel arguments. + *
USE_CONSTANT_CACHE Option to use registers to cache constant values otherwise constants are inlined. + *
SHOW_USE_COUNT Generates information on the number of times a register is used. + *
USE_INDEX_CACHE Option to use registers to cache array indicies. + *
Sanitizer Flags + *
SANITIZE_ADDRESS Use address sanitizer debugging option. + *
SANITIZE_LEAK Use leak sanitizer debugging option. + *
SANITIZE_MEMORY Use memory sanitizer debugging option. + *
SANITIZE_THREAD Use thread sanitizer debugging option. + *
SANITIZE_UNDEFINED Use undefined sanitizer debugging option. + *
SANITIZE_FLOAT-DIVIDE-BY-ZEROUse float-divide-by-zero sanitizer debugging option. + *
+ */ diff --git a/graph_docs/general.dox b/graph_docs/general.dox new file mode 100644 index 0000000000000000000000000000000000000000..3e72d2120a11bcc1a13b2683129827e16bd44bbe --- /dev/null +++ b/graph_docs/general.dox @@ -0,0 +1,134 @@ +/*! + * @page general_concepts General Concepts + * @brief Overview of basic concepts of the graph_framework. + * @tableofcontents + * @section general_concepts_introduction Introduction + * This page documents general concepts of the graph_framework. + * + * @section general_concepts_definitions Definitions + * + * + *
Glossery of terms
Concept Definition + *
node A leaf or branch on the graph tree. + *
graph A data stucture connecting nodes. + *
reduce A transformation of the graph to remove leaf_nodes. + *
auto differentiationA transformation of the graph build derivatives. + *
compiler A tool for translating from one language to another. + *
JIT Just-in-time compile. + *
kernel A code function that runs on a batch of data. + *
pre_item A kernel to run before running the main kernels. + *
work_iten A instance of kernel. + *
converge_item A kernel that is run until a convergence test is met. + *
workflow A series of work items. + *
backend The device the kernel is run on. + *
recursion See definition of recursion. + *
safe math Run time checks to avoid off normal conditions. + *
API Application programming interface. + *
Host The place where kernels are launched from. + *
Device The side where kernels are run. + *
+ * + *
+ * @section general_concepts_graph Graph + * The graph_framework operates by building a tree structure of math operations. + * For an example of building expression structures see the + * @ref tutorial_expression "basic expressions tutroial". In tree form it is + * easy to traverse nodes in the graph. Take the example of equation of a line. + * @f{equation}{y=mx + b@f} + * This equation consists of five nodes. The ends of the tree are clasified + * as either variables @f$x@f$ or constants @f$m,b@f$. These nodes are connected + * by nodes for multiply and addition operations. The output @f$y@f$ represents + * the entire graph of operations. + * @image{} html line_graph.png "The graph stucture for y = mx + b." + * Evaluation of graphs start from the top most node in this case the @f$+@f$ + * operation. Evaluation of a node is not performed until all subnodes are + * evaluated starting with the left operand. Evaluation starts by recursively + * evaluating the left operands until the last node is reached @f$m@f$. + * @image{} html line_graph_eval1.png "" + * Once @f$m@f$ the result is returned to the @f$+@f$ then the right operand is + * evaluated. + * @image{} html line_graph_eval2.png "" + * Evaluation is repeated until every node in the graph is evaluated. + * @image{} html line_graph_eval_final.png "" + * + *
+ * @section general_concepts_diff Auto Differentiation + * From the previous @ref general_concepts_graph "section", it was shown how + * graphs can be evaluated. This same evaluation can be applied to build + * graphs of a function derivative. For an example of taking derivatives see the + * @ref tutorial_derivatives "auto differentiation tutroial". Lets say that we + * want to take the derivative of @f$\frac{\partial y}{\partial x}@f$. This is + * achieved by evaluating the until bottom left most node is reached. Then a new + * graph is build starting with @f$\frac{\partial m}{\partial x}=0@f$. Applying + * the first half of the chain rule we build a new graph for @f$0x@f$ + * @image{} html line_graph_dydf1.png "" + * Then we take the derivative of the right operand and apply the second half + * of the chain rule to build a new graph for @f$0x=0@f$. + * @image{} html line_graph_dydf2.png "" + * Evaluation is repeated recursively until the full graph has been evaluated. + * @image{} html line_graph_dydf_final.png "" + * + *
+ * @section general_concepts_reduction Reduction + * The final expression for @f$\frac{\partial y}{\partial x}@f$ contains many + * unnecessary nodes in the graph. Instead of building full graphs, we can + * simplify and eleminate nodes as we build them. For instance, when the + * expression @f$0x@f$ this created can be immediately reduce it to a single + * node. + * @image{} html line_graph_reduce1.png "" + * Applying all possible reductions reduces the final expression to + * @f$\frac{\partial y}{\partial x}=m@f$. + * @image{} html line_graph_reduce_final.png "" + * By reducing graphs as they are build, we can eliminate nodes one by one. + * + *
+ * @section general_concepts_compile Compile + * Once graph expressions are built, they can be compiled to a compute kernel. + * For an example of compiling expression trees into kernels see the + * @ref tutorial_workflow "workflow tutroial". + * Using the same recursive evaluation, we can visit each node of a graph and + * and create a line of kernel source code. There are three important parts for + * creating kernels, inputs, outputs, and maps. These three concepts define + * buffers on the compute device and how they are changed. Compute kernels can + * be genereted from multiple outputs and maps. + * + * @subsection general_concepts_compile_inputs Inputs + * Inputs are the variable nodes that define the graph inputs. In the line + * example @f$\frac{\partial y}{\partial x}@f$, the input variable would be the + * node for @f$x@f$. Some graphs have no inputs. The graph for + * @f$\frac{\partial y}{\partial x}=m@f$ has eliminated all the variable nodes + * in the graph. + * + * @subsection general_concepts_compile_outputs Outputs + * Outputs are the ends of the nodes. These are the values we want to compute. + * Any node of a graph can be a potential output. For each output a device + * buffer is generated to store the results of the evalutaion. For nodes that + * are not used as outputs, no buffers need to be created since those results + * are never stored. + * + * @subsection general_concepts_compile_maps Maps + * Maps enable the results of an output node to be stored in an input node. This + * is use for a wide varity of steps. For instance take a gradient decent step. + * @f{equation}{y = y + \frac{\partial f}{\partial x}@f} + * In this case the output of the expression + * @f$y + \frac{\partial f}{\partial x}@f$ + * can be mapped to update @f$y@f$. + * + *
+ * @section general_concepts_workflow Workflows + * Sequences of kernels are evaluated in workflow. A workflow is defined from + * workitems which wrap a kernel call. + * + *
+ * @section general_concepts_safe_math Safe Math + * There are some conditions where mathematically, a graph should evaluate to a + * normal number. However, when evaluted suing floating point precison, can lead + * to Inf or NaN. An example of this the + * @f$\exp\left(x\right)@f$ function. For large argument values, + * @f$\exp\left(x\right)@f$ overflows the maximum floating point precision and + * returns Inf. @f$\frac{1}{\exp\left(x\right)}@f$ should evaluate + * zero however, in floating point this becomes a NaN. Safe math avoids + * problems like this by checking for large argument values. But since these + * run time checks slow down kernel evaluation, most of the time safe math + * should be avoided. + */ diff --git a/graph_docs/line_graph.png b/graph_docs/line_graph.png new file mode 100644 index 0000000000000000000000000000000000000000..f850d2c9a870541135d519c955b0b9567f24fc68 Binary files /dev/null and b/graph_docs/line_graph.png differ diff --git a/graph_docs/line_graph_dydf1.png b/graph_docs/line_graph_dydf1.png new file mode 100644 index 0000000000000000000000000000000000000000..b712c1aa1a4916d0b4e6b8697522b95afa9c3b95 Binary files /dev/null and b/graph_docs/line_graph_dydf1.png differ diff --git a/graph_docs/line_graph_dydf2.png b/graph_docs/line_graph_dydf2.png new file mode 100644 index 0000000000000000000000000000000000000000..0f718a4eb3dbeab1f7fd6f31c39da6bc6f0047c7 Binary files /dev/null and b/graph_docs/line_graph_dydf2.png differ diff --git a/graph_docs/line_graph_dydf_final.png b/graph_docs/line_graph_dydf_final.png new file mode 100644 index 0000000000000000000000000000000000000000..cbf1d52a26173b089a2094fc06c4fbfb38f080f4 Binary files /dev/null and b/graph_docs/line_graph_dydf_final.png differ diff --git a/graph_docs/line_graph_eval1.png b/graph_docs/line_graph_eval1.png new file mode 100644 index 0000000000000000000000000000000000000000..b2ff29e7115267336a679b5b529b05e5a56fa4ab Binary files /dev/null and b/graph_docs/line_graph_eval1.png differ diff --git a/graph_docs/line_graph_eval2.png b/graph_docs/line_graph_eval2.png new file mode 100644 index 0000000000000000000000000000000000000000..321e46d2d6c8363820d8682492a66539bfc38e0c Binary files /dev/null and b/graph_docs/line_graph_eval2.png differ diff --git a/graph_docs/line_graph_eval_final.png b/graph_docs/line_graph_eval_final.png new file mode 100644 index 0000000000000000000000000000000000000000..f48057248e0cc1b6ff07ad6439b0266ad4313de7 Binary files /dev/null and b/graph_docs/line_graph_eval_final.png differ diff --git a/graph_docs/line_graph_reduce1.png b/graph_docs/line_graph_reduce1.png new file mode 100644 index 0000000000000000000000000000000000000000..493caed7d90c8de0d087e1ed5ee199de0ad9ad35 Binary files /dev/null and b/graph_docs/line_graph_reduce1.png differ diff --git a/graph_docs/line_graph_reduce_final.png b/graph_docs/line_graph_reduce_final.png new file mode 100644 index 0000000000000000000000000000000000000000..bec19e9907c31a0db97243d9e78eb48cc9c87f0d Binary files /dev/null and b/graph_docs/line_graph_reduce_final.png differ diff --git a/graph_docs/main.dox b/graph_docs/main.dox new file mode 100644 index 0000000000000000000000000000000000000000..2e311c18695d915e4942406b3058cd78ab4b50ed --- /dev/null +++ b/graph_docs/main.dox @@ -0,0 +1,56 @@ +/*! + * @mainpage + * @tableofcontents + * @section introduction Introduction + * The graph_framework + * is a domain specific compiler for translating physics equations to optimized + * code that runs on GPUs and CPUs. The domain specific aspect limits this to + * classes of problems where the same physics is applied to an ensemble. Eamples + * include RF Ray tracing, particle pushing, and field line following. + * + * @subsection purpose Purpose + * The purpose of this framework is to enable domain scientists to write code + * that can run on any GPU and interface them with legacy codes. + * + * This framework enables: + * * Portability to Nvidia, AMD, and Apple GPUs and CPUs. + * * Abstraction of the physics from the compute. + * * Enable Auto Differentiation. + * * Enable easy embedding in C, C++, and Fortran codes. + * + *
+ * @section tools User guides for tools + * @subsection rf_ray_tracing RF Ray tracing + * This section covers user guides to run the RF Ray tracing code. To run this + * code, a user selects an equilibrium, a wave distribution function, a solver + * method, intial ray conditions, and a power obsorption model. To run an + * example follow the instructions for the @ref xrays_commandline_example. + * + * * @ref equilibrum_models + * * @ref dispersion_function + * * @ref solvers + * * @ref absorption_model + * * @ref xrays_commandline + * * @ref xrays_output + * + *
+ * @section framework_user Framework user guides + * * @ref build_system "Compiling the framework." + * * @ref general_concepts "General concepts." + * * @ref tutorial "Tutorial" + * * @ref graph_c_binding + * * @ref graph_fortran_binding + * + *
+ * @section framework_developer Framework developer guides + * * @ref build_system + * * @ref code_structure + * * @ref new_operations_tutorial + * + * @subsection framework_developer_tools Developer guide for RF Ray Tracing + * * @ref code_structure_xrays "Code Structure" + * * @ref equilibrum_devel + * * @ref dispersion_function_devel + * * @ref solvers_devel + * * @ref absorption_model_devel + */ diff --git a/graph_docs/tutorial.dox b/graph_docs/tutorial.dox new file mode 100644 index 0000000000000000000000000000000000000000..aa25e246be6ddd43b443915f0c24b748edc7baf1 --- /dev/null +++ b/graph_docs/tutorial.dox @@ -0,0 +1,396 @@ +/*! + * @page tutorial Tutorial + * @brief Hands on tutorial for building expressions and running workflows. + * @tableofcontents + * + * @section tutorial_introduction Introduction + * In this tutorial we will put the basic @ref general_concepts of the + * graph_framework into action. This will discuss building trees, generating + * kernels, and executing workflows. + * + * To accomplish this there is a playground tool in the + * graph_playground directory. This playground is a preconfigured + * executable target which can be used to test out the API's of this framework. + * The playground starts with a blank main function. + * @code +#include "../graph_framework/jit.hpp" + +int main(int argc, const char * argv[]) { + START_GPU + (void)argc; + (void)argv; + +// Insert code here. No code should be commited to this file beyond this +// template. + + END_GPU +} + @endcode + * To start, create a template function above main and call that function from + * main. This will allow us to play with different floating point types. For now + * we will start with a simple float type. + * @code +#include "../graph_framework/jit.hpp" + +template +void run_tutorial() { + +} + +int main(int argc, const char * argv[]) { + START_GPU + (void)argc; + (void)argv; + + run_tutorial (); + + END_GPU +} + @endcode + * Here @ref jit::float_scalar is a + * C++20 + * Concept of + * valid floating point types allowed by the framework. + * + *
+ * @section tutorial_basic Basic Nodes + * The graph_framework is built around applying the same equations to a large + * ensemble. Ensembles are defined from variables. All variables need to have + * same dimensionality. To create a variable we use one of the variable factory + * methods. For now we will build it without initalizing it. + * @code +template +void run_tutorial() { + auto x = graph::variable (1000, "x"); +} + @endcode + * Here we are creating a @ref graph::variable_node with the symbol @f$x@f$ + * which holds 1000 elements. The symbol is used by the @f$\LaTeX@f$ renderer + * as a symbol place holder. Any graph can be rendered to @f$\LaTeX@f$ by + * calling the @ref graph::leaf_node::to_latex method. + * @code +template +void run_tutorial() { + auto x = graph::variable (1000, "x"); + x->to_latex(); + std::cout << std::endl; +} + @endcode + * When compiling and running the code, this will print out the @f$\LaTeX@f$ + * code needed to generate the equation. By copy and pasting this into + * @f$\LaTeX@f$ it produces the symbol @f$x@f$. Note that all nodes of a graph + * are wrapped in a + * std::shared_ptr. + * so all method are called using the -> operator. + * + * @subsection tutorial_constant Constant Nodes + * Next we want to define a constant. There are two method to define constants + * explicitly or implicitly. + * @code +template +void run_tutorial() { + auto x = graph::variable(1000, "x"); + +// Define explicit constant. + auto m = graph::constant (0.4); +// Define implicit constant. + const T b = 0.6; +} + @endcode + * An explicit @ref graph::constant_node is created for m while an + * impicit constant was defined for b. Note in the implicit case, the + * actual node for b is not created until we use it in an expression. + * + *
+ * @section tutorial_expression Basic Expressions + * Finally lets create our equation of a line @f$y=mx+b@f$ and generate the + * @f$\LaTeX@f$ expression for it. + * @code +template +void run_tutorial() { + auto x = graph::variable(1000, "x"); + +// Define explicit constant. + auto m = graph::constant (0.4); +// Define implicit constant. + const T b = 0.6; + +// Equation of a line + auto y = m*x + b; + y->to_latex(); + std::cout << std::endl; +} + @endcode + * Running this will generate the output \\left(0.4 x+0.6\\right) which + * renders to @f$\left(0.4 x+0.6\right)@f$. + * + * @subsection tutorial_derivatives Auto Differentiation + * Derivatives of nodes can be taken with respect to any explicit node or graph. + * As an example lets take the @f$\frac{\partial y}{\partial x}@f$ and render + * the expression to latex. + * @code +template +void run_tutorial() { + auto x = graph::variable(1000, "x"); + +// Define explicit constant. + auto m = graph::constant (0.4); +// Define implicit constant. + const T b = 0.6; + +// Equation of a line + auto y = m*x + b; + +// Auto differentiation. + auto dydx = y->df(x); + dydx->to_latex(); + std::cout << std::endl; +} + @endcode + * Here we take derivatives using the @ref graph::leaf_node::df method. We can + * also take several variations of this. + * @code +auto dydm = y->df(m); +auto dydy = y->df(y); +auto dydb = y->df(m*x); + @endcode + * The results will be @f$0.4@f$, @f$x@f$, @f$1@f$, and @f$0@f$ respectively. + * + *
+ * @section tutorial_workflow Making workflows. + * In this section we will build a workflow from these nodes we created. For + * simplicity we will decrease the number of elements in the variable so we can + * set the values easier. First thing we do is create a @ref workflow::manager. + * @code +template +void run_tutorial() { + auto x = graph::variable(3, "x"); + +// Define explicit constant. + auto m = graph::constant (0.4); +// Define implicit constant. + const T b = 0.6; + +// Equation of a line + auto y = m*x + b; + +// Auto differentiation. + auto dydx = y->df(x); + +// Create a workflow manager. + workflow::manager work(0); +} + @endcode + * This creates a workflow for device 0. + * + * To create a kernal, we add a @ref workflow::work_item using the + * @ref workflow::manager::add_item method. + * @code +workflow::manager work(0); +work.add_item({ + graph::variable_cast(x) +}, { + y, dydx +}, {}, NULL, "my_first_kernel", 3); + @endcode + * Here we have created a kernel which computes the outputs of @f$y@f$ and + * @f$\frac{\partial y}{\partial x}@f$. The third and forth arguments are blank + * because there are no maps and we are not using random numbers. The last + * argument needs to match the dimensions of the inputs. Inputs need to be cast + * from generic @ref graph::leaf_node to the specific + * @ref graph::variable_node. + * + * To evaluate the kernel, we need to first compile it. Then set the values for + * @f$x@f$ and run the kernel. To see the results we can print the values of the + * nodes used. + * @code +x->set({1.0, 2.0, 3.0}); + +workflow::manager work(0); +work.add_item({ + graph::variable_cast(x) +}, { + y, dydx +}, {}, NULL, "my_first_kernel", 3); +work.compile(); + +work.run(); +work.print(0, {x, y, dydx}); +work.print(1, {x, y, dydx}); +work.print(2, {x, y, dydx}); + @endcode + * Running this we get the output + * @code +1 1 0.4 +2 1.4 0.4 +3 1.8 0.4 + @endcode + * + * At this point it's important to understand some things that need to be taken + * into account when working with devices. Note that we needed to set the value + * of @f$x@f$ before we create the kernel since that's when the device buffers + * are populated. If we move that to after the kernel is generated. + * @code +workflow::manager work(0); +work.add_item({ + graph::variable_cast(x) +}, { + y, dydx +}, {}, NULL, "my_first_kernel", 3); +work.compile(); + +x->set({1.0, 2.0, 3.0}); + +work.run(); +work.print(0, {x, y, dydx}); +work.print(1, {x, y, dydx}); +work.print(2, {x, y, dydx}); + @endcode + * We get the output + * @code +0 0.6 0.4 +0 0.6 0.4 +0 0.6 0.4 + @endcode + * showing that the device dose not have the updated values. To set values from + * the host. You need to explicity copy from a host buffer to a device buffer + * using the @ref workflow::manager::copy_to_device method. + * @code +work.copy_to_device(x, std::array ({1.0, 2.0, 3.0}).data()); + +work.run(); +work.print(0, {x, y, dydx}); +work.print(1, {x, y, dydx}); +work.print(2, {x, y, dydx}); + @endcode + * This restores the expected result. + * @code +1 1 0.4 +2 1.4 0.4 +3 1.8 0.4 + @endcode + * + * @subsection tutorial_workflow_iter Iteration + * In this section we are going to make use of maps to iterate a variable. We + * want to evaluate the value of @f$y@f$ and set it as the new value of @f$x@f$. + * We do this my modifying call to @ref workflow::manager::add_item to define + * a map. This generates a kernel where after @f$y@f$ is computed it is stored + * in the @f$x@f$ buffer. + * @code +x->set({1.0, 2.0, 3.0}); + +workflow::manager work(0); +work.add_item({ + graph::variable_cast(x) +}, {}, { + {y, graph::variable_cast(x)} +}, NULL, "iteration_kernel", 3); +work.compile(); + +for (size_t i = 0; i < 10; i++) { + work.run(); + work.print(1, {x}); +} + @endcode + * Running this code shows the value of x continously updating. + * @code +1.4 +1.16 +1.064 +1.0256 +1.01024 +1.0041 +1.00164 +1.00066 +1.00026 +1.0001 + @endcode + * + *
+ * @section tutorial_workflow_newton Newton's Method. + * In this tutorial we are going to show how we can put all these concepts + * together to implement a Newton's method. Newton's method is defined as + * @f{equation}{x = x - \frac{f\left(x\right)}{\frac{\partial}{\partial x}f\left(x\right)}@f} + * From the iteration example, its step update can be handled by a simple map. + * However, we need a measure for convergence. To do that we output the value of + * @f$f\left(x\right)@f$. Lets setup a test function. + * @code +template +void run_tutorial() { + auto x = graph::variable (3, "x"); + x->set({1.0, 2.0, 3.0}); + +// Define an objective function. + auto f = 0.2*x*x*x + 0.6*x*x + 0.4*x + 0.5; + +// Define a step update. + auto x_new = x - f/f->df(x); + +// Create a workflow manager. + workflow::manager work(0); + work.add_item({ + graph::variable_cast(x) + }, {f}, { + {x_new, graph::variable_cast(x)} + }, NULL, "newton_kernel", 3); + work.compile(); + + std::array result; + T max; + do { + work.run(); + work.copy_to_host(f, result.data()); + max = 0.0; + for (T &r : result) { + max = std::max(max, r*r); + } + std::cout << max << std::endl; + } while (max > 1.0E-10); + work.print(0, {x}); + work.print(1, {x}); + work.print(2, {x}); +} + @endcode + * Running shows the objective function and all three elements found the same + * root. + * @code +156.25 +14.2408 +1.47246 +... +5.30397e-06 +8.50397e-12 +3.03979e-15 +-2.6006 +-2.6006 +-2.6006 + @endcode + * + * However there are some things that are not optimial here. We are performing + * a reduction on the host side and transfering the entire array to the host. To + * improve this we can use a converge item instead. + * @code +// Create a workflow manager. +workflow::manager work(0); +work.add_converge_item({ + graph::variable_cast(x) +}, {f*f}, { + {x_new, graph::variable_cast(x)} +}, NULL, "newton_kernel", 3, 1.0E-14); +work.compile(); + +work.run(); +work.print(0, {x}); +work.print(1, {x}); +work.print(2, {x}); +} + @endcode + * We can achieve the same result in a single run call. The advantage here is + * the reduction is now performed on the device and only a scalar is copied to + * the host to test for convergence. + * @code +-2.6006 +-2.6006 +-2.6006 + @endcode + */ diff --git a/graph_docs/vmec.png b/graph_docs/vmec.png new file mode 100644 index 0000000000000000000000000000000000000000..8a36cf3d90943cb608c322fac1ef0da8e6e402cf Binary files /dev/null and b/graph_docs/vmec.png differ diff --git a/graph_driver/xrays.cpp b/graph_driver/xrays.cpp index ad2531e4011a9f8a0eae8db8cf46f10f420a6410..347d67e66413f7111f31f3eabc13bcc9ca68ec85 100644 --- a/graph_driver/xrays.cpp +++ b/graph_driver/xrays.cpp @@ -45,7 +45,7 @@ std::normal_distribution> set_distribution(const std::complex /// @brief Initalize value. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] cl Parsed commandline. /// @param[in,out] var Variable to set. @@ -367,7 +367,7 @@ void run_dispersion(const commandline::parser &cl, /// @brief Make an equilibrum. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] cl Parsed commandline. //------------------------------------------------------------------------------ @@ -402,7 +402,7 @@ std::mt19937_64 make_engine(const commandline::parser &cl, /// @brief Trace the rays. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] cl Parsed commandline. /// @param[in] num_times Total number of time steps. @@ -414,7 +414,7 @@ void trace_ray(const commandline::parser &cl, const size_t num_times, const size_t sub_steps, const size_t num_rays) { - const timeing::measure_diagnostic total("Total Ray Time"); + const timing::measure_diagnostic total("Total Ray Time"); std::vector threads(std::max(std::min(static_cast (jit::context::max_concurrency()), static_cast (num_rays)), @@ -533,7 +533,9 @@ void trace_ray(const commandline::parser &cl, /// /// @tparam ABSORPTION_MODEL Absoption model to use. /// +/// @param[in] cl Parsed commandline. /// @param[in] kamp Wave number amplitude. +/// @param[in] omega Wave frequency. /// @param[in] kx Wave number in x direction. /// @param[in] ky Wave number in y direction. /// @param[in] kz Wave number in z direction. @@ -586,7 +588,7 @@ void run_absorption(const commandline::parser &cl, /// @brief Calculate absorption. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] cl Parsed commandline. /// @param[in] num_times Total number of time steps. @@ -598,7 +600,7 @@ void calculate_power(const commandline::parser &cl, const size_t num_times, const size_t sub_steps, const size_t num_rays) { - const timeing::measure_diagnostic total("Power Time"); + const timing::measure_diagnostic total("Power Time"); std::vector threads(std::max(std::min(static_cast (jit::context::max_concurrency()), static_cast (num_rays)), @@ -661,7 +663,7 @@ void calculate_power(const commandline::parser &cl, /// @brief Bin power. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] cl Parsed commandline. /// @param[in] num_times Total number of time steps. @@ -673,7 +675,7 @@ void bin_power(const commandline::parser &cl, const size_t num_times, const size_t sub_steps, const size_t num_rays) { - const timeing::measure_diagnostic total("Power Time"); + const timing::measure_diagnostic total("Power Time"); std::vector threads(std::max(std::min(static_cast (jit::context::max_concurrency()), static_cast (num_rays)), @@ -790,6 +792,160 @@ void bin_power(const commandline::parser &cl, total.print(); } +//------------------------------------------------------------------------------ +/// @page xrays_commandline xrays Command Line Arguments +/// @brief Command Line Arguments for the xrays RF Ray tracing code. +/// @tableofcontents +/// +/// @section xrays_commandline_intro Introduction +/// This page documents the commandline arguments or the RF ray tracing code +/// xrays. All arguments take the form of +/// @code +/// xrays [--options] [--options=with_value] +/// @endcode +/// +/// @section xrays_commandline_args Command Options +/// +///
Command Values Discription +///
General Options +///
@code --help @endcode Display help text +///
@code --verbose @endcode Show verbose output about kernel information. +///
@code --print_expressions @endcode Render ray equations as @f$\LaTeX@f$ expressions. +///
@code --print @endcode Display a sample of ray progress to the screen. +///
@code --seed @endcode Use a fixed random seed. +///
Control Options +///
@code --num_times @endcode Positive Integer Total number of time steps to run. +///
@code --sub_steps @endcode Positive Integer Number of steps to run between outputs. +///
@code --num_rays @endcode Positive Integer Total number rays to run. +///
@code --endtime @endcode Positive Number Total time to trace the ray to. +///
Ray Initialization Options +///
@code --init_w_dist @endcode +/// * uniform +/// * normal Distribution function for wave frequency. +///
@code --init_w_mean @endcode Positive Number Mean value for the wave frequency distribution function. +///
@code --init_w_sigma @endcode Positive Number Standard deviation of for the wave frequency distribution function. +///
@code --init_kx_dist @endcode +/// * uniform +/// * normal Distribution function for wave number in the x direction. +///
@code --init_kx @endcode Solve for initial wave number in the x direction position. +///
@code --init_kx_mean @endcode Positive Number Mean value for the wave number in the x direction distribution function. +///
@code --init_kx_sigma @endcode Positive Number Standard deviation of for the wave number in the y direction distribution function. +///
@code --init_ky_dist @endcode +/// * uniform +/// * normal Distribution function for wave number in the y direction. +///
@code --init_ky @endcode Solve for initial wave number in the y direction position. +///
@code --init_ky_mean @endcode Positive Number Mean value for the wave number in the y direction distribution function. +///
@code --init_ky_sigma @endcode Positive Number Standard deviation of for the wave number in the y direction distribution function. +///
@code --init_kz_dist @endcode +/// * uniform +/// * normal Distribution function for wave number in the z direction. +///
@code --init_kz @endcode Solve for initial wave number in the z direction position. +///
@code --init_kz_mean @endcode Positive Number Mean value for the wave number in the z direction distribution function. +///
@code --init_kz_sigma @endcode Positive Number Standard deviation of for the wave number in the z direction distribution function. +///
@code --init_x_dist @endcode +/// * uniform +/// * normal Distribution function for ray x position. +///
@code --init_x_mean @endcode Positive Number Mean value for the ray x position distribution function. +///
@code --init_x_sigma @endcode Positive Number Standard deviation of for the ray x position distribution function. +///
@code --init_y_dist @endcode +/// * uniform +/// * normal Distribution function for ray y position. +///
@code --init_y_mean @endcode Positive Number Mean value for the ray y position distribution function. +///
@code --init_y_sigma @endcode Positive Number Standard deviation of for the ray y position distribution function. +///
@code --init_z_dist @endcode +/// * uniform +/// * normal Distribution function for ray z position. +///
@code --init_z_mean @endcode Positive Number Mean value for the ray z position distribution function. +///
@code --init_z_sigma @endcode Positive Number Standard deviation of for the ray z position distribution function. +///
@code --use_cyl_xy @endcode Use cylindical coordinates for x and y. +///
Ray Tracing Physics Options +///
@code --equilibrium @endcode +/// * @ref equilibrum_efit "efit" +/// * @ref equilibrum_vmec "vmec" Equilibrium to use. +///
@code --equilibrium_file @endcode Path to @ref equilibrum_models "equilibrium file" Equilibrium file path. +///
@code --dispersion @endcode +/// * @ref dispersion_function_simple "simple" +/// * @ref dispersion_function_bohm_gross "bohm_gross" +/// * @ref dispersion_function_o_wave "ordinary_wave" +/// * @ref dispersion_function_x_wave "extra_ordinary_wave" +/// * @ref dispersion_function_cold_plasma "code_plasma" Wave disperion function to trace rays from. +///
@code --absorption_model @endcode +/// * @ref absorption_model_root "root_find" +/// * @ref absorption_model_root "weak_damping" Power absoption model to use. +///
@code --solver @endcode +/// * @ref solvers_split_simplextic "split_simplextic" +/// * @ref solvers_rk2 "rk2" +/// * @ref solvers_rk4 "rk4" +/// * @ref solvers_adaptive_rk4 "adaptive_rk4" Method used to solve the equation. +///
+/// +///
+/// @section xrays_commandline_example Example commandline +/// Take the example command line +/// @code +/// ./graph_driver/xrays --absorption_model=weak_damping --dispersion=ordinary_wave --endtime=2.0 --equilibrium=efit --equilibrium_file=../graph_tests/efit.nc --init_kx --init_kx_mean=-700.0 --init_ky_dist=normal --init_ky_mean=-100.0 --init_ky_sigma=10.0 --init_kz_dist=normal --init_kz_mean=0.0 --init_kz_sigma=10.0 --init_w_dist=normal --init_w_mean=700 --init_w_sigma=10.0 --init_x_mean=2.5 --init_y_dist=normal --init_y_mean=0.0 --init_y_sigma=0.05 --init_z_dist=normal --init_z_mean=0.0 --init_z_sigma=0.05 --num_rays=100000 --num_times=100000 --solver=rk4 --sub_steps=100 --use_cyl_xy --verbose +/// @endcode +/// This example should be run from the build directory. +/// +/// The options +/// @code +/// --num_rays=100000 --num_times=100000 --sub_steps=100 --verbose +/// @endcode +/// In this example, we will run a 100000 rays for 100000 steps and output +/// every 100th step. This is also the provides verbose output of the kernel +/// information. +/// +/// @code +/// --endtime=2.0 --init_w_mean=700 +/// @endcode +/// Time and frequency are input in +/// @ref dispersion_function_normal "modified units". +/// +/// +///
Conversion between input and real units.
Value Input ValueReal Unit +///
@f$\omega @f$700 @f$\frac{700}{c}@f$ @f$\frac{rad}{s}@f$ +///
@f$t @f$ 2.0 @f$2.0c @f$ @f$s @f$ +///
+/// +/// @subsection xrays_commandline_example_dist Ray intialization. +/// @code +/// --init_x_mean=2.5 --init_y_dist=normal --init_y_mean=0.0 --init_y_sigma=0.05 --init_z_dist=normal --init_z_mean=0.0 --init_z_sigma=0.05 --use_cyl_xy +/// @endcode +/// Inital values for the position for @f$y @f$ and @f$z @f$ will be sampled +/// from a normal distribution fuction. Both values have a mean of zero and as +/// standard devation of 0.05. @f$x @f$ is initalized with a uniform value of +/// 2.5. We also set the command to use cylindical coordinates. So +/// @f$xyz\rightarrow r\phi z @f$. +/// +/// @code +/// --init_w_dist=normal --init_w_mean=700 --init_w_sigma=10.0 +/// @endcode +/// Frequency uses a normal distribution with a mean of 700 and a standard +/// deviation of 10. +/// +/// @code +/// --init_kx --init_kx_mean=-700.0 --init_ky_dist=normal --init_ky_mean=-100.0 --init_ky_sigma=10.0 --init_kz_dist=normal --init_kz_mean=0.0 --init_kz_sigma=10.0 +/// @endcode +/// Inital values for @f$k_{y}@f$ and @f$k_{z}@f$ will be sampled from a normal +/// distribution fuction. Both of them have a standard deviation of 10. +/// @f$k_{y}@f$ has a mean of -100 and @f$k_{z}@f$ has zero mean. +/// @f$k_{x}@f$ uses the default uniform value of -700.0. However, it is +/// configured to solve for @f$k_{x}@f$ which satisfies the dispersion function +/// given the values of @f$\omega,k_{y},k_{z},\vec{x}@f$. +/// +/// @subsection xrays_commandline_example_model Ray Models. +/// @code +/// --equilibrium=efit --equilibrium_file=../graph_tests/efit.nc +/// @endcode +/// We are using a @ref equilibrum_efit "EFIT" equilibirum with values +/// initalized from ../graph_tests/efit.nc. +/// +/// @code +/// --absorption_model=weak_damping --dispersion=ordinary_wave --solver=rk4 +/// @endcode +/// It uses the @ref dispersion_function_o_wave "o-mode" dispersion function. +/// Rays are integrated using a @ref solvers_rk4 integrator. Power absorption +/// uses the @ref absorption_model_damping Model. //------------------------------------------------------------------------------ /// @brief Setup and parse commandline options. /// @@ -798,20 +954,20 @@ void bin_power(const commandline::parser &cl, //------------------------------------------------------------------------------ commandline::parser parse_commandline(int argc, const char * argv[]) { commandline::parser cl(argv[0]); - cl.add_option("verbose", false, "Show verbose output."); - cl.add_option("num_times", true, "Number of times."); - cl.add_option("sub_steps", true, "Number of substeps."); + cl.add_option("verbose", false, "Show verbose output about kernel information."); + cl.add_option("num_times", true, "Total number of time steps to run."); + cl.add_option("sub_steps", true, "Number of steps to run between outputs."); cl.add_option("num_rays", true, "Number of rays."); cl.add_option("endtime", true, "End time."); - cl.add_option("print_expressions", false, "Print out rays expressions."); + cl.add_option("print_expressions", false, "Render ray equations as LaTeX expressions."); cl.add_option("print", false, "Print sample rays to screen."); - cl.add_option("solver", true, "Solver method.", { + cl.add_option("solver", true, "Method used to solve the equation.", { "split_simplextic", "rk2", "rk4", "adaptive_rk4" }); - cl.add_option("dispersion", true, "Disperison method.", { + cl.add_option("dispersion", true, "Wave disperion function to trace rays from.", { "simple", "bohm_gross", "ordinary_wave", @@ -823,51 +979,51 @@ commandline::parser parse_commandline(int argc, const char * argv[]) { "vmec" }); cl.add_option("equilibrium_file", true, "File to read the equilibrum from."); - cl.add_option("init_w_dist", true, "Inital omega distribution.", { + cl.add_option("init_w_dist", true, "Distribution function for wave frequency.", { "uniform", "normal" }); - cl.add_option("init_w_mean", true, "Inital omega mean"); - cl.add_option("init_w_sigma", true, "Inital omega sigma"); - cl.add_option("init_kx_dist", true, "Inital kx distribution.", { + cl.add_option("init_w_mean", true, "Mean value for the wave frequency distribution function."); + cl.add_option("init_w_sigma", true, "Standard deviation of for the wave frequency distribution function."); + cl.add_option("init_kx_dist", true, "Distribution function for wave number in the x direction.", { "uniform", "normal" }); - cl.add_option("init_kx", false, "Initalize kx"); - cl.add_option("init_kx_mean", true, "Inital kx mean"); - cl.add_option("init_kx_sigma", true, "Inital kx sigma"); - cl.add_option("init_ky_dist", true, "Inital ky distribution.", { + cl.add_option("init_kx", false, "Solve for initial wave number in the x direction position."); + cl.add_option("init_kx_mean", true, "Mean value for the wave number in the x direction distribution function."); + cl.add_option("init_kx_sigma", true, "Standard deviation of for the wave number in the x direction distribution function."); + cl.add_option("init_ky_dist", true, "Distribution function for wave number in the y direction.", { "uniform", "normal" }); - cl.add_option("init_ky", false, "Initalize ky"); - cl.add_option("init_ky_mean", true, "Inital ky mean"); - cl.add_option("init_ky_sigma", true, "Inital ky sigma"); + cl.add_option("init_ky", false, "Solve for initial wave number in the y direction position."); + cl.add_option("init_ky_mean", true, "Mean value for the wave number in they direction distribution function."); + cl.add_option("init_ky_sigma", true, "Standard deviation of for the wave number in the y direction distribution function."); cl.add_option("init_kz_dist", true, "Inital kz distribution.", { "uniform", "normal" }); - cl.add_option("init_kz", false, "Initalize kz"); - cl.add_option("init_kz_mean", true, "Inital kz mean"); - cl.add_option("init_kz_sigma", true, "Inital kz sigma"); - cl.add_option("init_x_dist", true, "Inital x distribution.", { + cl.add_option("init_kz", false, "Distribution function for wave number in the z direction."); + cl.add_option("init_kz_mean", true, "Solve for initial wave number in the z direction position."); + cl.add_option("init_kz_sigma", true, "Standard deviation of for the wave number in the z direction distribution function."); + cl.add_option("init_x_dist", true, "Distribution function for ray x position.", { "uniform", "normal" }); - cl.add_option("init_x_mean", true, "Inital x mean"); - cl.add_option("init_x_sigma", true, "Inital x sigma"); - cl.add_option("init_y_dist", true, "Inital y distribution.", { + cl.add_option("init_x_mean", true, "Mean value for the ray x position distribution function."); + cl.add_option("init_x_sigma", true, "Standard deviation of for the ray x position distribution function."); + cl.add_option("init_y_dist", true, "Distribution function for ray y position.", { "uniform", "normal" }); - cl.add_option("init_y_mean", true, "Inital y mean"); - cl.add_option("init_y_sigma", true, "Inital y sigma"); - cl.add_option("init_z_dist", true, "Inital z distribution.", { + cl.add_option("init_y_mean", true, "Mean value for the ray y position distribution function."); + cl.add_option("init_y_sigma", true, "Standard deviation of for the ray y position distribution function."); + cl.add_option("init_z_dist", true, "Distribution function for ray z position.", { "uniform", "normal" }); - cl.add_option("init_z_mean", true, "Inital z mean"); - cl.add_option("init_z_sigma", true, "Inital z sigma"); + cl.add_option("init_z_mean", true, "Mean value for the ray z position distribution function."); + cl.add_option("init_z_sigma", true, "Standard deviation of for the ray z position distribution function."); cl.add_option("use_cyl_xy", false, "Use cylindical coordinates for x and y."); cl.add_option("absorption_model", true, "Power absoption model to use.", { "root_find", @@ -880,6 +1036,44 @@ commandline::parser parse_commandline(int argc, const char * argv[]) { return cl; } +//------------------------------------------------------------------------------ +/// @page xrays_output xrays Output File +/// @brief Result file format for the traced rays. +/// @tableofcontents +/// +/// @section xrays_output_intro Introduction +/// The results of ray tracing are saved in several NetCDF files depending on +/// how many devices were found. The files have the name format of +/// resultn.nc. +/// +/// @section xrays_output_format File Format +/// The result file contains the following information. Note that to allow for +/// complex values, we add an extra dimension the end of 2D arrays. For real +/// values this dimension has size one while complex values have space for the +/// real and imaginary part. +/// +/// +///
Result file quantities
Dimensions +///
Name Discription +///
time Size of time dimension. +///
num_rays Local number of rays for the device. +///
ray_dim Size of the dimension for quanties. (1 Real, 2 Complex) +///
ray_dim_cplx Size of the dimension for complex quantities (Real, Imagine). +///
2D Qantities +///
Name Dimensions Discription +///
d_power (time,num_rays,ray_dim) Change in power. +///
kamp (time,num_rays,ray_dim_cplx)@f$\sqrt{\vec{k}\cdot\vec{k}}@f$ +///
kx (time,num_rays,ray_dim) Wave number in @f$\hat{x}@f$ direction. +///
ky (time,num_rays,ray_dim) Wave number in @f$\hat{y}@f$ direction. +///
kz (time,num_rays,ray_dim) Wave number in @f$\hat{z}@f$ direction. +///
power (time,num_rays,ray_dim) Wave power. +///
residule(time,num_rays,ray_dim) Dispersion function residule. +///
time (time,num_rays,ray_dim) Time +///
w (time,num_rays,ray_dim) Wave frequency. +///
x (time,num_rays,ray_dim) Position in @f$\hat{x}@f$ direction. +///
y (time,num_rays,ray_dim) Position in @f$\hat{y}@f$ direction. +///
z (time,num_rays,ray_dim) Position in @f$\hat{z}@f$ direction. +///
//------------------------------------------------------------------------------ /// @brief Main program of the driver. /// @@ -890,7 +1084,7 @@ int main(int argc, const char * argv[]) { START_GPU (void)argc; (void)argv; - const timeing::measure_diagnostic total("Total Time"); + const timing::measure_diagnostic total("Total Time"); const commandline::parser cl = parse_commandline(argc, argv); jit::verbose = cl.is_option_set("verbose"); diff --git a/graph_fortran_binding/graph_fortran_binding.f90 b/graph_fortran_binding/graph_fortran_binding.f90 index bc539bc0e9f83ab5ee2427bd9691d1a07c87d25f..183b4e11b0202010f4f17aab4f2eb2385dc00296 100644 --- a/graph_fortran_binding/graph_fortran_binding.f90 +++ b/graph_fortran_binding/graph_fortran_binding.f90 @@ -1,12 +1,85 @@ !------------------------------------------------------------------------------- !> @file graph_fortran_binding.f90 !> @brief Implimentation of the Fortran binding library. -! -! Note separating the Doxygen comment block here so the detailed description is -! found in the Module not the file. -! -!> Module contains subroutines for calling this from fortran. !------------------------------------------------------------------------------- +!> @page graph_fortran_binding Embedding in Fortran code +!> @brief Documentation for linking into a Fortran code base. +!> @tableofcontents +!> +!> @section graph_fortran_binding_into Introduction +!> This section assumes the reader is already familar with developing Fortran +!> codes. The simplist method is to create a C callable function like the +!> @ref graph_c_binding_into "C binding exmaple". Then create a Fortran +!> interface for it. +!> @code +!> INTERFACE +!> SUBROUTINE Fortran_Callable BIND(C, NAME='c_callable_function') +!> USE, INTRINSIC :: ISO_C_BINDING +!> IMPLICIT NONE +!> END SUBROUTINE +!> END INTERFACE +!> @endcode +!> This subroutine can be called like any other Fortran subroutine. +!> @code +!> CALL Fortran_Callable +!> @endcode +!> +!>
+!> @section graph_fortran_binding_interface Fortran Binding Interface +!> An alternative is to use the +!> @ref graph_fortran "Fortran Language interface". The Fortran binding +!> interface can be enabled as one of the cmake +!> @ref build_system_user_options "conifgure options". As an example, we will +!> convert the @ref tutorial_workflow "making workflows" turorial to use the +!> Fortran language bindings. +!> @code +!> SUBROUTINE fortran_binding +!> USE graph_fortran +!> USE, INTRINSIC :: ISO_C_BINDING +!> +!> IMPLICIT NONE +!> +!> CLASS(graph_context), POINTER :: graph +!> TYPE(C_PTR) :: x +!> TYPE(C_PTR) :: m +!> TYPE(C_PTR) :: b +!> TYPE(C_PTR) :: y +!> TYPE(C_PTR) :: dydx +!> +!> LOGICAL(C_BOOL), PARAMETER :: use_safe_math = .false. +!> +!> graph => graph_double_context(use_safe_math); +!> +!> x = graph%variable(1_C_LONG, 'x' // C_NULL_CHAR) +!> m = graph%constant(0.4_C_DOUBLE) +!> b = graph%constant(0.6_C_DOUBLE) +!> +!> y = graph%add(graph%mul(m, x), b) +!> dydx = graph%df(y, x); +!> +!> CALL graph%set_variable(x, (/ 1.0_C_DOUBLE, 2.0_C_DOUBLE, 3.0_C_DOUBLE /)) +!> +!> CALL graph%set_device_number(0) +!> CALL graph%add_item((/ graph_ptr(x) /), & +!> (/ graph_ptr(y), graph_ptr(dydx) /)) & +!> graph_null_array, graph_null_array, C_NULL_PTR, & +!> 'my_first_kernel' // C_NULL_CHAR, 3_C_LONG) +!> CALL graph%compile +!> CALL graph%run +!> CALL graph%print(0, (/ graph_ptr(x), graph_ptr(y), graph_ptr(dydx) /)) +!> CALL graph%print(1, (/ graph_ptr(x), graph_ptr(y), graph_ptr(dydx) /)) +!> CALL graph%print(2, (/ graph_ptr(x), graph_ptr(y), graph_ptr(dydx) /)) +!> +!> DEALLOCATE(graph) +!> END SUBROUTINE +!> @endcode +!> +!> @note Graphs need to use the @ref graph_fortran::graph_ptr function to get +!> the pointer address of node. +!> @note The @ref graph_fortran::graph_null_array allows setting array of nodes +!> arguments to null. +!------------------------------------------------------------------------------- +!> Module contains subroutines for calling this from fortran. MODULE graph_fortran USE, INTRINSIC :: ISO_C_BINDING @@ -14,7 +87,6 @@ !> A null array for empty INTEGER(C_INTPTR_T), DIMENSION(0) :: graph_null_array -!> A !------------------------------------------------------------------------------- !> @brief Class object for the binding. @@ -994,6 +1066,7 @@ !> @param[in,out] this @ref graph_context instance. !> @param[in] size Size of the data buffer. !> @param[in] symbol Symbol of the variable. +!> @returns A variable node. !------------------------------------------------------------------------------- FUNCTION graph_context_variable(this, size, symbol) @@ -1011,10 +1084,11 @@ END FUNCTION !------------------------------------------------------------------------------- -!> @brief Create variable node. +!> @brief Create a constant node. !> !> @param[in,out] this @ref graph_context instance. !> @param[in] value Size of the data buffer. +!> @returns A constant node. !------------------------------------------------------------------------------- FUNCTION graph_context_constant_real(this, value) @@ -1115,11 +1189,12 @@ END SUBROUTINE !------------------------------------------------------------------------------- -!> @brief Create variable node. +!> @brief Create constant node with complex values. !> !> @param[in,out] this @ref graph_context instance. !> @param[in] real_value The real component. !> @param[in] img_value The imaginary component. +!> @returns A constant node. !------------------------------------------------------------------------------- FUNCTION graph_context_constant_complex(this, real_value, img_value) @@ -1138,7 +1213,7 @@ END FUNCTION !------------------------------------------------------------------------------- -!> @brief Create variable node. +!> @brief Create pseudo variable node. !> !> @param[in,out] this @ref graph_context instance. !> @param[in] var The variable to set. @@ -1913,6 +1988,8 @@ !> @param[in] random_state Optional random state, can be NULL if not used. !> @param[in] name Name for the kernel. !> @param[in] num_particles Number of elements to operate on. +!> @param[in] tol Maximum tolarance to converge to. +!> @param[in] max_iter Maximum number of iterations for convergence. !------------------------------------------------------------------------------- SUBROUTINE graph_context_add_converge_item(this, inputs, outputs, & map_inputs, map_outputs, & diff --git a/graph_framework.xcodeproj/project.pbxproj b/graph_framework.xcodeproj/project.pbxproj index 593bf91bdda794160090abef0f0420cd1abb14ab..854d12d198e8b4ef540713483f122e2bc9192d33 100644 --- a/graph_framework.xcodeproj/project.pbxproj +++ b/graph_framework.xcodeproj/project.pbxproj @@ -355,6 +355,10 @@ C73BBE7D29F816E60027BB7F /* piecewise_test.cpp */ = {isa = PBXFileReference; explicitFileType = sourcecode.cpp.objcpp; path = piecewise_test.cpp; sourceTree = ""; }; C73BBE9629F8669F0027BB7F /* newton.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = newton.hpp; sourceTree = ""; }; C74DF4572AA8BC7300319113 /* graph_benchmark */ = {isa = PBXFileReference; explicitFileType = "compiled.mach-o.executable"; includeInIndex = 0; path = graph_benchmark; sourceTree = BUILT_PRODUCTS_DIR; }; + C75C42912E5CA60B00B0950B /* compiling.dox */ = {isa = PBXFileReference; lastKnownFileType = text; path = compiling.dox; sourceTree = ""; }; + C75C42922E5CA60B00B0950B /* general.dox */ = {isa = PBXFileReference; lastKnownFileType = text; path = general.dox; sourceTree = ""; }; + C75C42932E5CA60B00B0950B /* main.dox */ = {isa = PBXFileReference; lastKnownFileType = text; path = main.dox; sourceTree = ""; }; + C75C42952E5CC80B00B0950B /* tutorial.dox */ = {isa = PBXFileReference; lastKnownFileType = text; path = tutorial.dox; sourceTree = ""; }; C760B1AB2BC6D760001737A3 /* get_includes.py */ = {isa = PBXFileReference; lastKnownFileType = text.script.python; path = get_includes.py; sourceTree = ""; }; C7678FBD2B45C2850025F37E /* bin.py */ = {isa = PBXFileReference; lastKnownFileType = text.script.python; path = bin.py; sourceTree = ""; }; C77E6DF522DD64E700469621 /* trigonometry.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = trigonometry.hpp; sourceTree = ""; }; @@ -395,6 +399,8 @@ C7DC9EE82E39789900524F6F /* libgraph_c.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = libgraph_c.a; sourceTree = BUILT_PRODUCTS_DIR; }; C7DC9EEF2E397BE600524F6F /* Cocoa.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Cocoa.framework; path = System/Library/Frameworks/Cocoa.framework; sourceTree = SDKROOT; }; C7DC9EF12E3A688F00524F6F /* c_binding_test.c */ = {isa = PBXFileReference; explicitFileType = sourcecode.c.objc; path = c_binding_test.c; sourceTree = ""; }; + C7DD87D32E664B440058BA66 /* code_structure.dox */ = {isa = PBXFileReference; lastKnownFileType = text; path = code_structure.dox; sourceTree = ""; }; + C7DD87D42E665E260058BA66 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = ""; }; C7E134492A3CB3EC0083F6A7 /* output.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = output.hpp; sourceTree = ""; }; C7E5643E28A2A16F000F31A2 /* backend_test */ = {isa = PBXFileReference; explicitFileType = "compiled.mach-o.executable"; includeInIndex = 0; path = backend_test; sourceTree = BUILT_PRODUCTS_DIR; }; C7E5644A28A2A1C5000F31A2 /* dispersion_test */ = {isa = PBXFileReference; explicitFileType = "compiled.mach-o.executable"; includeInIndex = 0; path = dispersion_test; sourceTree = BUILT_PRODUCTS_DIR; }; @@ -608,6 +614,18 @@ path = graph_benchmark; sourceTree = ""; }; + C75C42942E5CA60B00B0950B /* graph_docs */ = { + isa = PBXGroup; + children = ( + C75C42912E5CA60B00B0950B /* compiling.dox */, + C75C42922E5CA60B00B0950B /* general.dox */, + C75C42932E5CA60B00B0950B /* main.dox */, + C75C42952E5CC80B00B0950B /* tutorial.dox */, + C7DD87D32E664B440058BA66 /* code_structure.dox */, + ); + path = graph_docs; + sourceTree = ""; + }; C78F3D892DC122B1002E3D94 /* graph_korc */ = { isa = PBXGroup; children = ( @@ -621,6 +639,7 @@ isa = PBXGroup; children = ( C7931E7228073BFC0033B488 /* CMakeLists.txt */, + C7DD87D42E665E260058BA66 /* README.md */, C79141AD22DA9C0600E0BA0D /* graph_framework */, C7931E6928073BCA0033B488 /* graph_tests */, C7DC9EE32E39768300524F6F /* graph_c_binding */, @@ -629,6 +648,7 @@ C74DF4582AA8BC7300319113 /* graph_benchmark */, C736E6B02C9B52CA00AAE3C0 /* graph_playground */, C78F3D892DC122B1002E3D94 /* graph_korc */, + C75C42942E5CA60B00B0950B /* graph_docs */, C7167B212AC5CE8500E03131 /* utilities */, C717CB8C2A02E361008FBDD8 /* cmake */, C79141A722DA9BF200E0BA0D /* Products */, diff --git a/graph_framework/absorption.hpp b/graph_framework/absorption.hpp index bb9a416615af62710672494d33f8e7352d497a1f..7119a064ea7b45f9fe43f26512523287c90b6f73 100644 --- a/graph_framework/absorption.hpp +++ b/graph_framework/absorption.hpp @@ -4,7 +4,90 @@ /// /// Defines functions for computing power absorbtion. //------------------------------------------------------------------------------ - +//------------------------------------------------------------------------------ +/// @page absorption_model Absoption Models +/// @brief A discription of the models for power absorption. +/// @tableofcontents +/// +/// @section absorption_model_intro Introduction +/// This page documents the types of dispersion functions available. Tracing +/// the ray is only the first step in the process. Along that, ray power is +/// deposited into the plasma. For tracing the ray we assumed the wave number +/// was always real. However, now we need to figure out what the imaginary +/// component is. +/// +///
+/// @subsection absorption_model_hot Hot Plasma Disperison Function +/// To do this we now assume a hot plasma dispersion function. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=i\sigma\Gamma_{0}+\Gamma_{1}+\vec{n}_{\perp}\cdot\vec{n}_{\perp}\frac{P\omega}{\omega_{ce}}\left(1+\zeta Z\left(\zeta\right)\right)\left(\Gamma_{2} + \Gamma_{5}F\right)\equiv 0 @f} +/// Where +/// @f{equation}{\Gamma_{0}=\vec{n}_{\perp}\cdot\vec{n}_{\perp}\left(\vec{n}\cdot\vec{n}-2\left(1-2q\right)\right)+\left(1-P\right)\left(2\left(1-2q\right)-\left(\vec{n}\cdot\vec{n}+n_{||}^{2}\right)\right)@f} +/// @f{equation}{\Gamma_{1}=\vec{n}_{\perp}\cdot\vec{n}_{\perp}\left(\left(1-q\right)\vec{n}\cdot\vec{n}-(1-2q)\right)+\left(1-P\right)\left(\vec{n}\cdot\vec{n}n^{2}_{||} - \left(1-q\right)\left(\vec{n}\cdot\vec{n}+n^{2}_{||}\right)+\left(1-2q\right)\right)@f} +/// @f{equation}{\Gamma_{2}=\left(\vec{n}\cdot\vec{n}-\left(1-2q\right)\right)+\frac{P\omega}{4\omega_{ce}n^{2}_{||}}\left(\left(\vec{n}\cdot\vec{n} + n^{2}_{||}\right)-2\left(1-2q\right)\right)@f} +/// @f{equation}{\Gamma_{5}=\vec{n}\cdot\vec{n}n^{2}_{||}-\left(1-q\right)\left(\vec{n}\cdot\vec{n}+n^{2}_{||}\right)+\left(1-2q\right)@f} +/// @f{equation}{i\sigma=\frac{PZ\left(\zeta\right)}{2n_{||}v_{e}}@f} +/// @f{equation}{\zeta=\frac{1-\frac{\omega_{ce}}{\omega}}{n_{||}\frac{v_{e}}{c}}@f} +/// @f{equation}{F=\frac{v_{e}\left(1+\zeta Z\left(\zeta\right)\right)\omega}{2n_{||}\omega_{ce}}@f} +/// @f{equation}{P=\frac{\omega^{2}_{pe}}{\omega^{2}}@f} +/// @f{equation}{q=\frac{P}{2\left(1+\frac{\omega_{ce}}{\omega}\right)}@f} +/// @f{equation}{v_{e}=\sqrt{2n_{e}\frac{t_{e}}{m_{e}}}@f} +/// @f{equation}{Z\left(\zeta\right)=-\sqrt{\pi}e^{-\zeta^{s}}\left(efri\left(\zeta\right)-i\right)@f} +/// Where @f$efri\left(\zeta\right)@f$ is the imaginary error function. +/// +/// @subsubsection absorption_model_hotexpand Expansion Terms +/// The hot plasma dispersion function can be split to a hot plasma term and a +/// cold plasma term. +/// @f{equation}{D_{c}\left(\vec{x},\vec{k},\omega\right)=-\frac{P}{2}\left(1+\frac{\omega_{ce}}{\omega}\Gamma_{0}+\left(1-\frac{\omega^{2}_{ce}}{\omega^{2}}\Gamma_{1}\right)\right)@f} +/// Then the hot plasma term is +/// @f{equation}{D_{h}\left(\vec{x},\vec{k},\omega\right)=-\left(1+\frac{\omega_{ce}}{\omega}\right)n_{||}\frac{v_{e}}{c}\left(\Gamma_{1}+\Gamma_{2}+\frac{\vec{n}_{\perp}\cdot\vec{n}_{\perp}}{2n^{2}_{||}}\frac{\omega^{2}}{\omega^{2}_{ce}}\frac{v_{e}}{c}\zeta\Gamma_{5}\right)\left(\frac{1}{Z\left(\zeta\right)}+\zeta\right)@f} +/// +///
+/// @section absorption_model_root Root Find +/// One way to solve for the imaginary component is to locate the root of the +/// hot plasma dispersion function using the cold plasma solution as an intial +/// quess. We start by redefining @f$\vec{k}=k_{amp}\hat{k}@f$ now we can solve +/// for the complex value of @f$k_{amp}@f$ using a +/// @ref solver::newton "Newton method". +/// +///
+/// @section absorption_model_damping Weak Damping +/// Using the cold and hot expansion +/// @f{equation}{k_{amp}=\sqrt{\vec{k}\cdot\vec{k}}-\frac{D_{h}}{\hat{k}\cdot\frac{\partial D_{c}}{\partial \vec{k}}}@f} +/// +///
+/// @section absorption_model_devel Developing new absorption models +/// This section is intended for code developers and outlines how to create new +/// absorption models. New absorption models can be created from a subclass +/// of @ref absorption::method or any other existing +/// absorption class and overloading class methods. +/// @code +/// template +/// class new_absorption final : public method { +/// new_absorption(graph::shared_leaf kamp, +/// graph::shared_leaf w, +/// graph::shared_leaf kx, +/// graph::shared_leaf ky, +/// graph::shared_leaf kz, +/// graph::shared_leaf x, +/// graph::shared_leaf y, +/// graph::shared_leaf z, +/// graph::shared_leaf t, +/// equilibrium::shared &eq, +/// const std::string &filename="", +/// const size_t index=0) { +/// ... +/// } +/// +/// void compile() { +/// ... +/// } +/// +/// void run(const size_t time_index) { +/// ... +/// } +/// }; +/// @endcode +//------------------------------------------------------------------------------ #ifndef absorption_h #define absorption_h @@ -13,6 +96,7 @@ #include "newton.hpp" #include "output.hpp" +/// Namespace for power absorption models. namespace absorption { //****************************************************************************** // Base class @@ -21,7 +105,7 @@ namespace absorption { /// @brief Base class for absoption models. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class method { @@ -30,6 +114,18 @@ namespace absorption { typedef T base; /// Retrieve template parameter of safe math. static constexpr bool safe_math = SAFE_MATH; + +//------------------------------------------------------------------------------ +/// @brief Compile the workitems. +//------------------------------------------------------------------------------ + virtual void compile()=0; + +//------------------------------------------------------------------------------ +/// @brief Run the workflow. +/// +/// @param[in] time_index The time index to run the case for. +//------------------------------------------------------------------------------ + virtual void run(const size_t time_index)=0; }; /// Solver method concept. @@ -43,7 +139,7 @@ namespace absorption { /// @brief Class interface for the root finder. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class root_finder : public method { @@ -232,7 +328,7 @@ namespace absorption { /// @brief Class interface weak damping approximation. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class weak_damping : public method { diff --git a/graph_framework/arithmetic.hpp b/graph_framework/arithmetic.hpp index 51f0d904037a5e38e6ec0ae8dc3e75174a84686b..7d0d6d34f91c6f4af80983f31aadc97546a1d24d 100644 --- a/graph_framework/arithmetic.hpp +++ b/graph_framework/arithmetic.hpp @@ -15,7 +15,7 @@ namespace graph { /// @brief Check if nodes are constant combineable. /// /// @tparam T Base type of the nodes. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Opperand A /// @param[in] b Opperand B @@ -43,7 +43,7 @@ namespace graph { /// @brief Check if the constants are promotable. /// /// @tparam T Base type of the nodes. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Opperand A /// @param[in] b Opperand B @@ -65,7 +65,7 @@ namespace graph { /// @brief Check if the variable is combinable. /// /// @tparam T Base type of the nodes. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Opperand A /// @param[in] b Opperand B @@ -81,7 +81,7 @@ namespace graph { /// @brief Check if the variable is variable is promotable. /// /// @tparam T Base type of the nodes. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Opperand A /// @param[in] b Opperand B @@ -101,7 +101,7 @@ namespace graph { /// @brief Check if the exponent is greater than the other. /// /// @tparam T Base type of the nodes. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Opperand A /// @param[in] b Opperand B @@ -126,7 +126,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class add_node final : public branch_node { @@ -731,7 +731,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -765,7 +765,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -784,7 +784,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -803,7 +803,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -822,7 +822,7 @@ namespace graph { /// @brief Cast to a add node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -841,7 +841,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class subtract_node final : public branch_node { @@ -1553,7 +1553,7 @@ namespace graph { /// @brief Build subtract node from two leaves. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1588,7 +1588,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1608,7 +1608,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1628,7 +1628,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1647,7 +1647,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] a Argument to negate. /// @returns -1.0*a @@ -1665,7 +1665,7 @@ namespace graph { /// @brief Cast to a subtract node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -1682,7 +1682,7 @@ namespace graph { /// @brief A multiplcation node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class multiply_node final : public branch_node { @@ -2623,7 +2623,7 @@ namespace graph { /// @brief Build multiply node from two leaves. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -2657,7 +2657,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -2676,7 +2676,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -2695,7 +2695,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -2714,7 +2714,7 @@ namespace graph { /// @brief Cast to a multiply node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -2731,7 +2731,7 @@ namespace graph { /// @brief A division node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class divide_node final : public branch_node { @@ -3588,7 +3588,7 @@ namespace graph { /// @brief Build divide node from two leaves. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -3622,7 +3622,7 @@ namespace graph { /// classes. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -3641,7 +3641,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -3660,7 +3660,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -3679,7 +3679,7 @@ namespace graph { /// @brief Cast to a divide node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -3698,7 +3698,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class fma_node final : public triple_node { @@ -5192,7 +5192,7 @@ namespace graph { /// @brief Build fused multiply add node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5229,7 +5229,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5250,7 +5250,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam M Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5271,7 +5271,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5293,7 +5293,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. /// @tparam M Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5316,7 +5316,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam M Float type for the constant. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5339,7 +5339,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] m Middle branch. @@ -5361,7 +5361,7 @@ namespace graph { /// @brief Cast to a fma node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. diff --git a/graph_framework/backend.hpp b/graph_framework/backend.hpp index 0ad9222fa6c3f2a01197fc849153e4a3a5726f1b..c95b65db030ff5675b096f35ad2ab2cf8b4de517 100644 --- a/graph_framework/backend.hpp +++ b/graph_framework/backend.hpp @@ -15,6 +15,7 @@ #include "special_functions.hpp" #include "register.hpp" +/// Name space for backend buffers. namespace backend { //****************************************************************************** // Data buffer. diff --git a/graph_framework/commandline_parser.hpp b/graph_framework/commandline_parser.hpp index ed73c24052cffc72bad07b59c229033a59e5150f..17b579575463cfe22d489bb09c9fdda80756da1e 100644 --- a/graph_framework/commandline_parser.hpp +++ b/graph_framework/commandline_parser.hpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file commandline\_parser.hpp +/// @file commandline_parser.hpp /// @brief Parsing routines for the command line. //------------------------------------------------------------------------------ @@ -11,6 +11,7 @@ #include #include +/// Name space for the command line parsing. namespace commandline { /// Lock to syncronize netcdf accross threads. static std::mutex sync; diff --git a/graph_framework/cpu_context.hpp b/graph_framework/cpu_context.hpp index 37b0e297076b1c2d8e313ef2040d7a016f06274d..05024f9b4eb670a9ce695b9bd5be376d43d8bc11 100644 --- a/graph_framework/cpu_context.hpp +++ b/graph_framework/cpu_context.hpp @@ -76,7 +76,7 @@ namespace gpu { /// @brief Class representing a cpu context. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class cpu_context { diff --git a/graph_framework/cuda_context.hpp b/graph_framework/cuda_context.hpp index e3c9ce0c6085c927599f4732ddc0f879cd083c7e..e2f31ac54adc52da0d25b9f64cfacb1cc5d2425c 100644 --- a/graph_framework/cuda_context.hpp +++ b/graph_framework/cuda_context.hpp @@ -17,8 +17,8 @@ #include "random.hpp" +/// Maximum number of registers to use. #define MAX_REG 128 -#define MAX_CONSTANT_MEMORY namespace gpu { //------------------------------------------------------------------------------ @@ -67,7 +67,7 @@ namespace gpu { /// @brief Class representing a cuda gpu context. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class cuda_context { diff --git a/graph_framework/dispersion.hpp b/graph_framework/dispersion.hpp index 40ecdabd05022a23fe673cabada114f28e1d37d3..0727f38eee9421102a37a637d49b12538734aa63 100644 --- a/graph_framework/dispersion.hpp +++ b/graph_framework/dispersion.hpp @@ -4,6 +4,147 @@ /// /// Defines a dispersion function. //------------------------------------------------------------------------------ +//------------------------------------------------------------------------------ +/// @page dispersion_function Dispersion Functions +/// @brief Dispersion function documentation for the xrays RF Ray tracing code. +/// @tableofcontents +/// +/// @section dispersion_function_intro Introduction +/// This page documents the types of dispersion functions available. As a ray +/// moves through the plasma it must remain a solution of these functions. For +/// a fixed wave frequency @f$\omega @f$, the dispersion function dictates how +/// the wave number @f$\vec{k}@f$ and ray trajectory +/// @f$\vec{x}@f$ interact. +/// +/// +///
Symbol definitions
Symbol Unit Description +///
@f$c @f$ @f$\frac{m}{s}@f$Speed of light. +///
@f$m_{e}@f$ @f$kg @f$ Electron mass +///
@f$t_{e}@f$ @f$K @f$ Electron temperature +///
@f$n_{e}@f$ @f$m^{-3}@f$ Electron Denisty +///
@f$q @f$ @f$C @f$ Fundamental Charge +///
@f$\vec{B}@f$ @f$T @f$ Magnetic field +///
@f$\epsilon_{0}@f$@f$\frac{F}{m}@f$Vacuum permittivity +///
@f$k_{B}@f$ @f$\frac{J}{K}@f$Boltzmann constant +///
@f$\omega_{pe}@f$ @f$s^{-1}@f$ Electron Plasma Frequency @f$\omega_{pe}=\frac{n_{e}q^{2}}{\epsilon_{0}m_{e}c}@f$ +///
@f$\omega_{ce}@f$ @f$s^{-1}@f$ Electron Cyclotron Frequency @f$\omega_{ce}=\frac{q\left|\vec{B}\right|}{m_{e}}@f$ +///
@f$\omega_{h}@f$ @f$s^{-1}@f$ Upper Hybrid Frequency @f$\omega_{h}^{s}=\omega_{pe}^{2}+\omega_{ce}^{2}@f$ +///
@f$\omega_{r}@f$ @f$s^{-1}@f$ Right cutoff Frequency @f$\omega_{r}=\frac{1}{2}\left(\omega_{ce}+\sqrt{\omega^{2}_{ce}+4\omega_{pe}^{2}}\right)@f$ +///
@f$\omega_{l}@f$ @f$s^{-1}@f$ Left cutoff Frequency @f$\omega_{r}=\frac{1}{2}\left(-\omega_{ce}+\sqrt{\omega^{2}_{ce}+4\omega_{pe}^{2}}\right)@f$ +///
@f$v_{th}@f$ @f$\frac{m}{s}@f$Thermal velocity @f$v_{th}=\sqrt{\frac{k_{B}t_{e}}{m_{e}}}@f$ +///
@f$\vec{n}@f$ @f$1 @f$ @f$n=\frac{\vec{k}c}{\omega}@f$ +///
+/// +/// @section dispersion_function_normal Normalization +/// The dispersion functions use normalized quantities for frequncy @f$\omega @f$ and +/// time @f$t @f$. These are scaled to the speed of light @f$c @f$. +/// +/// +///
Disperion function units and normalizations
Symbol Real Unit Modified Modified UnitDescription +///
@f$\omega @f$ @f$s^{-1}@f$ @f$\omega'=\frac{\omega}{c}@f$ @f$m^{-1}@f$ Wave frequency +///
@f$\vec{k}@f$ @f$m^{-1}@f$ @f$\vec{k}@f$ @f$m^{-1}@f$ Wave number +///
@f$t @f$ @f$s @f$ @f$t'=tc @f$ @f$m @f$ Time +///
@f$\vec{x}@f$ @f$m @f$ @f$\vec{x}@f$ @f$m @f$ Postion +///
@f$v_{p}=\frac{\omega}{k}@f$ @f$\frac{m}{s}@f$@f$v'_{p}=\frac{\omega'}{k}@f$ @f$1 @f$ Phase velocity +///
@f$v_{g}=\frac{\partial\omega}{\partial k}@f$@f$\frac{m}{s}@f$@f$v'_{g}=\frac{\partial\omega'}{\partial k}@f$@f$1 @f$ Group velocity +///
+/// +/// @section dispersion_function_wave_propagation Wave propagation +/// From any dispersion function, the wave propagation equations are obtained +/// from derivatives of the dispersion relation. +/// @f{equation}{\frac{\partial\vec{x}}{\partial {t}}=-\frac{\frac{\partial D}{\partial\vec{k}}}{\frac{\partial D}{\partial\omega}}@f} +/// @f{equation}{\frac{\partial\vec{k}}{\partial {t}}=\frac{\frac{\partial D}{\partial\vec{x}}}{\frac{\partial D}{\partial\omega}}@f} +/// RF waves are traced by integrating this system of equations. +/// +/// @section dispersion_function_avail Available Dispersion Functions +/// The following dispersion functions are available in xrays. +/// +/// @subsection dispersion_function_simple Simple +/// This disperison function represents a wave in a vacuum. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=\frac{\vec{k}\cdot\vec{k}}{\omega^{2}}-1\equiv 0 @f} +/// It has no resonances or cutoffs. +/// +///
+/// @subsection dispersion_function_bohm_gross Bohm Gross +/// This dispersion function now accounts for how occilations in the plasma +/// propagate. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=\omega_{pe}+\frac{3}{2}\vec{k}\cdot\vec{k}v^{2}_{th}-\omega^{2}\equiv 0 @f} +/// It has no resonances. Waves cannot propagate below @f$\omega_{pe}@f$ and @f$v_{g}@f$ can never exceed @f$v_{th}@f$. +/// @image{} html bohm-gross.png "" +/// +///
+/// @subsection dispersion_function_o_wave Ordinary Wave +/// This disperison function represents a wave with a +/// @f$\vec{E}_{1}||\vec{B}_{0}@f$. That means the electric field occilates +/// parallel to the magnetic field. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=1-\frac{\omega^{2}_{pe}}{\omega^{2}}-\vec{n}_{\perp}\cdot\vec{n}_{\perp}\equiv 0 @f} +/// This wave is cut off below @f$\omega_{pe}@f$. +/// @image{} html O-Mode.png "" +/// +///
+/// @subsection dispersion_function_x_wave Extra Ordinary Wave +/// This disperison function represents a wave with a +/// @f$\vec{E}_{1}\perp\vec{B}_{0}@f$. That means the electric field occilates +/// perpendicular to the magnetic field. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=1-\frac{\omega_{pe}^2}{\omega^{2}}\frac{\omega^{2}-\omega_{pe}^2}{\omega^{2}-\omega_{h}^2}-\vec{n}_{\perp}\cdot\vec{n}_{\perp}\equiv 0 @f} +/// This mode has +/// This wave has two branches. One branch is cannot not progagate below the +/// @f$\omega_{r}@f$ cutoff. The other branch cannot not progagate below the +/// @f$\omega_{l}@f$ cutoff. As the wave approches the upper hybrid fequency, +/// wave propagation stops as the wave number approces +/// @f$\left|\vec{k}\right|\rightarrow\infty @f$. +/// @image{} html X-Mode.png "" +/// +///
+/// @subsection dispersion_function_cold_plasma Cold Plasma +/// This disperison function represents a wave in a cold plasma medium. +/// @f{equation}{D\left(\vec{x},\vec{k},\omega\right)=det\left(\vec{\epsilon}+\vec{n}\vec{n}-\vec{n}\cdot\vec{n}\vec{I}\right)\equiv 0 @f} +/// The quantity @f$\vec{\epsilon}@f$ is the diaelectric tensor. Using Onsager +/// symmetries, this tensor is defined as +/// @f{equation}{\vec{\epsilon}=\left(\begin{array}{ccc}\epsilon_{11}&\epsilon_{12}&0\\-\epsilon_{12}&\epsilon_{11}&0\\0&0&\epsilon_{33}\end{array}\right)@f} +/// where +/// @f{equation}{\epsilon_{11}=1-\sum_{s}\frac{\frac{\omega^{2}_{p}}{\omega^{2}}}{1-\frac{\Omega^{2}_{c}}{\omega^{2}}}@f} +/// @f{equation}{\epsilon_{12}=-i\sum_{s}\frac{\frac{\Omega_{c}}{\omega}\frac{\omega^{2}_{p}}{\omega^{2}}}{1-\frac{\Omega^{2}_{c}}{\omega^{2}}}@f} +/// @f{equation}{\epsilon_{33}=1-\sum_{s}\frac{\omega^{2}_{p}}{\omega^{2}}@f} +/// Note here we are including the plasma frequency for ions aswell. This +/// dispersion function is effectively a super position of the O-Mode and +/// X-Mode dispersion functions and as such has the same cutoffs and resonaces. +/// @image{} html ColdPlasma.png "" +/// +///
+/// @section dispersion_function_devel Developing new dispersion functions +/// This section is intended for code developers and outlines how to create new +/// dispersion functions. New dispersion functions can be created from a +/// subclass of @ref dispersion::dispersion_function or any other existing +/// dispersion_function class and overloading class methods. For convinence the +/// @ref dispersion::physics class contains several defined physical constants. +/// @code +/// template +/// class new_dispersion final : public dispersion_function { +/// ... +/// }; +/// @endcode +/// When a new dispersion function is subclassed from +/// @ref dispersion::dispersion_function an implimentation must be provided for +/// the pure virtual method @ref dispersion::dispersion_function::D. +/// @code +/// template +/// class new_dispersion final : public dispersion_function { +/// public: +/// virtual graph::shared_leaf D(graph::shared_leaf w, +/// graph::shared_leaf kx, +/// graph::shared_leaf ky, +/// graph::shared_leaf kz, +/// graph::shared_leaf x, +/// graph::shared_leaf y, +/// graph::shared_leaf z, +/// graph::shared_leaf t, +/// equilibrium::shared &eq) { +/// ... +/// } +/// }; +/// @endcode +//------------------------------------------------------------------------------ #ifndef dispersion_h #define dispersion_h @@ -11,6 +152,7 @@ #include "newton.hpp" #include "equilibrium.hpp" +/// Name space for dispersion functions. namespace dispersion { //****************************************************************************** // Z Function interface. @@ -19,7 +161,7 @@ namespace dispersion { /// @brief Class interface to build dispersion relation functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class z_function { @@ -43,7 +185,7 @@ namespace dispersion { /// @brief Class interface to build dispersion relation functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class z_power_series final : public z_function { @@ -70,7 +212,7 @@ namespace dispersion { /// @brief Class interface to build dispersion relation functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class z_erfi final : public z_function { @@ -99,7 +241,7 @@ namespace dispersion { /// @brief Build plasma fequency expression. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] n Density. /// @param[in] q Species charge. @@ -122,7 +264,7 @@ namespace dispersion { /// @brief Build cyclotron fequency expression. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] q Species charge. /// @param[in] b Magnetic field. @@ -146,7 +288,7 @@ namespace dispersion { /// @brief Interface for dispersion functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class dispersion_function { @@ -185,7 +327,7 @@ namespace dispersion { /// @brief Stiff dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class stiff final : public dispersion_function { @@ -240,7 +382,7 @@ namespace dispersion { /// @brief Simple dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class simple final : public dispersion_function { @@ -282,7 +424,7 @@ namespace dispersion { /// @brief Physics /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class physics : public dispersion_function { @@ -304,7 +446,7 @@ namespace dispersion { /// @brief Bohm-Gross dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class bohm_gross final : public physics { @@ -374,7 +516,7 @@ namespace dispersion { /// @brief Light Wave dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class light_wave final : public physics { @@ -433,7 +575,7 @@ namespace dispersion { /// @brief Ion wave dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class acoustic_wave final : public physics { @@ -497,7 +639,7 @@ namespace dispersion { /// @brief Guassian Well dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class guassian_well final : public dispersion_function { @@ -539,7 +681,7 @@ namespace dispersion { /// @brief Electrostatic ion cyclotron wave dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class ion_cyclotron final : public physics { @@ -608,7 +750,7 @@ namespace dispersion { /// @brief Ordinary wave dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class ordinary_wave final : public physics { @@ -667,7 +809,7 @@ namespace dispersion { /// @brief Extra ordinary wave dispersion function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class extra_ordinary_wave final : public physics { @@ -739,7 +881,7 @@ namespace dispersion { /// @brief Cold Plasma Disperison function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class cold_plasma : public physics { @@ -859,7 +1001,7 @@ namespace dispersion { /// @brief Cold Plasma expansion disperison function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class cold_plasma_expansion : public physics { @@ -1062,7 +1204,7 @@ namespace dispersion { /// /// @tparam T Base type of the calculation. /// @tparam Z Z function class. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class hot_plasma_expansion final : public physics { diff --git a/graph_framework/equilibrium.hpp b/graph_framework/equilibrium.hpp index 9707d1799884553f5ac9972343e1fd5b5a6fd7c3..4433fa07f6f4a7733c09ce944674e0c7540f240e 100644 --- a/graph_framework/equilibrium.hpp +++ b/graph_framework/equilibrium.hpp @@ -4,6 +4,207 @@ /// /// Defined the interfaces to access plasma equilibrium. //------------------------------------------------------------------------------ +/// @page equilibrum_models Equilibrium Models +/// @brief Documentation for formatting equilibrium files. +/// @tableofcontents +/// +/// @section equilibrum_models_intro Introduction +/// This page documents the types and formatting of the equilibrium models. +/// xrays currently supports two equilibrium models. +/// * EFIT Are 2D axisymetric equilibria relevant to tokamak devices. +/// * VMEC Are 3D nested flux surface equilibria relevant for stellarator devices. +/// +/// This documentation assumes the user has some familiarity with EFIT or VMEC +/// and focuses instead how quanties from these are formatted. +/// +/// @section equilibrum_splines Spline Formatting +/// The equilibrium models used in this section make use of Cubic and Bicubic +/// splines. +/// +///
+/// @subsection equilibrum_splines_1D Cubic Splines +/// Cubic splines are 1D interpolation functions consisting of 4 coeffient +/// arrays. They take the form of +/// @f{equation}{y\left(x\right)=C_{0} + C_{1}x + C_{2}x^2 + C_{3}x^2@f} +/// where @f$x@f$ is a normalized radial index. Cubic splines coefficients can +/// be calculated using +/// Linear Solvers +/// However, to avoid needing account for index offsets, index offsets are pre +/// computed into the spline coefficents. +/// @f{equation}{C'^{i}_{0}=C^{i}_{0} - C^{i}_{1}i + C^{i}_{2}i^2 - C^{i}_{3}i^3@f} +/// @f{equation}{C'^{i}_{1}=C^{i}_{1} -2C^{i}_{2}i + 3C^{i}_{3}i^2@f} +/// @f{equation}{C'^{i}_{2}=C^{i}_{2} - 3C^{i}_{3}i@f} +/// @f{equation}{C'^{i}_{3}=C^{i}_{3}@f} +/// Where @f$i@f$ is the index of the coeffient array. This allows to normalize +/// the spline argument @f$x@f$ so that it can both index the array and +/// evaluate the spline. +/// @f{equation}{x = \frac{x_{real} - x_{min}}{dx}@f} +/// Rounding down the value of @f$x@f$ gives the correct coefficient index. +/// +///
+/// @subsection equilibrum_splines_2D Bicubic Splines +/// Bicubic Splines are computed in a simular way instead they consist of a +/// total of 16 coeffients. These represent 4 spline functions in one +/// dimension which interpolate 4 coeffient values for the other dimension. +/// Like the 1D splines, 2D spline coeffients are normalized so the spline +/// arguments can be used as normalized indices. +/// @f{equation}{C'^{ij}_{00}=C^{ij}_{00}-C^{ij}_{01}j+C^{ij}_{02}j^{2}-C^{ij}_{03}j^{3}-C^{ij}_{10}i+C^{ij}_{11}ij-C^{ij}_{12}ij^{2}+C^{ij}_{13}ij^{3}+C^{ij}_{20}i^{2}-C^{ij}_{21}i^{2}j+C^{ij}_{22}i^{2}j^{2}-C^{ij}_{23}i^{2}j^{3}-C^{ij}_{30}i^{3}+C^{ij}_{31}i^{3}j-C^{ij}_{32}i^{3}j^{2}+C^{ij}_{33}i^{3}j^{3}j@f} +/// @f{equation}{C'^{ij}_{01}=C^{ij}_{01}-2C^{ij}_{02}j+3C^{ij}_{03}j^{2}-C^{ij}_{11}i+2C^{ij}_{12}ij-3C^{ij}_{13}ij^{2}+C^{ij}_{21}i^{2}-2C^{ij}_{22}i^{2}j+3C^{ij}_{23}i^{2}j^{2}-C^{ij}_{31}i^{3}+2C^{ij}_{32}i^{3}j-3C^{ij}_{33}i^{3}j^{2}@f} +/// @f{equation}{C'^{ij}_{02}=C^{ij}_{02}-3C^{ij}_{03}j-C^{ij}_{12}i+3C^{ij}_{13}ij+C^{22}i^{2}-3C^{ij}_{23}i^{2}j-C^{ij}_{32}i^{3}+3C^{ij}i^{3}j @f} +/// @f{equation}{C'^{ij}_{03}=C^{ij}_{03}-C^{ij}_{13}i+C^{ij}_{23}i^{2}-C^{ij}_{33}i^{3}@f} +/// @f{equation}{C'^{ij}_{10}=C^{ij}_{10}-2C^{ij}_{11}j+C^{ij}_{12}j^{2}-C^{ij}_{13}j^{3}-2C^{ij}_{20}i+2C^{ij}_{21}ij-2C^{ij}_{22}ij^{2}+2C^{ij}_{23}ij^{3}j+3C^{ij}_{30}i^{2}-3C^{ij}_{31}i^{2}j+3C^{ij}_{32}i^{2}j^{2}-3C^{ij}_{33}i^{2}j^{3}@f} +/// @f{equation}{C'^{ij}_{11}=C^{ij}_{11}-2C^{ij}_{12}j+3C^{ij}_{13}j^{2}-2C^{ij}_{21}i+4C^{ij}_{22}ij-6C^{ij}_{23}ij^{2}+3C^{ij}_{31}i^{2}-6C^{ij}_{32}i^{2}j+9C^{ij}_{33}i^{2}j^{2}@f} +/// @f{equation}{C'^{ij}_{12}=C^{ij}_{12}-C^{ij}_{13}j-2C^{ij}_{22}i+6C^{ij}_{23}ij+3C^{ij}_{32}j-9C^{ij}_{33}i^{2}j @f} +/// @f{equation}{C'^{ij}_{13}=C^{ij}_{13}-2C^{ij}_{23}i+3C^{ij}_{33}i^{2}@f} +/// @f{equation}{C'^{ij}_{20}=C^{ij}_{20}-C^{ij}_{21}j+C^{ij}_{22}ij^{2}-C^{ij}_{23}j^{3}-3C^{30}i+3C^{ij}_{31}ij-3C^{ij}_{32}ij^{2}+3C^{ij}_{33}ij^{3}@f} +/// @f{equation}{C'^{ij}_{21}=C^{ij}_{21}-2C^{ij}_{22}j+3C^{ij}_{23}j^{2}-3C^{ij}_{31}i+6C^{32}ij-9C^{ij}_{33}ij^{2}@f} +/// @f{equation}{C'^{ij}_{22}=C^{ij}_{22}-3C^{ij}_{23}j-3C^{ij}_{32}i+9C^{ij}_{33}ij @f} +/// @f{equation}{C'^{ij}_{23}=C^{ij}_{23}-3C^{ij}_{33}i @f} +/// @f{equation}{C'^{ij}_{30}=C^{ij}_{30}-C^{ij}_{31}j+C^{ij}_{32}j^{2}-C^{ij}_{33}j^{3}@f} +/// @f{equation}{C'^{ij}_{31}=C^{ij}_{31}-2C^{ij}_{32}j+3C^{ij}_{32}j^{2}@f} +/// @f{equation}{C'^{ij}_{32}=C^{ij}_{32}-3C^{ij}_{33}j @f} +/// @f{equation}{C'^{ij}_{33}=C^{ij}_{33} @f} +/// Bicubic splines are computed by +/// @f{equation}{f\left(x,y\right)=\left(\begin{array}{cccc}1 & x & x^{2} & x^{3}\end{array}\right)\cdot\left(\left(\begin{array}{cccc}C_{00}&C_{01}&C_{02}&C_{03}\\C_{10}&C_{11}&C_{12}&C_{13}\\C_{20}&C_{21}&C_{22}&C_{23}\\C_{30}&C_{31}&C_{32}&C_{33}\end{array}\right)\cdot\left(\begin{array}{c}1\\y\\y^{2}\\y^{3}\end{array}\right)\right)@f} +/// Like the 1D splines @f$x@f$ and @f$y@f$ are normalized. +/// @f{equation}{x = \frac{x_{real} - x_{min}}{dx}@f} +/// @f{equation}{y = \frac{y_{real} - y_{min}}{dy}@f} +/// +///
+/// @section equilibrum_efit EFIT +/// @image{} html Efit.png "Cross section of poloidal flux surfaces." +/// EFIT is an equilibium that comes from a solution of the +/// Grad–Shafranov equation. +/// The solution gives us a map of the poloidal flux @f$\psi@f$ on 2D grid and +/// a 1D flux function @f$f_{pol}@f$. 1D profiles of electrion density +/// @f$n_{e}\left(\psi\right)@f$, electron temperature +/// @f$t_{e}\left(\psi\right)@f$, and pressure @f$p\left(\psi\right)@f$ are +/// mapped as functions of the normalized flux. +/// +/// @subsection equilibrum_efit_format EFIT file format +/// Quantities are loaded into the ray tracer via a netcdf file. EFIT NetCDF +/// files must contain the following quantities. Spline quanities have a common +/// format of name_ci or name_cij. +/// +/// +///
Efit netcdf file quantities
Dimensions +///
Name Discription +///
numr Size of radial grid. +///
numz Size of vertical grid. +///
numpsi Size of arrays for @f$\psi@f$ mapped quantities. +///
Scalar Qantities +///
dpsi Step size of the @f$\psi@f$ grid. +///
dr Step size of the radial grid. +///
dz Step size of the vertial grid. +///
ne_scale Scale of the @f$n_{e}@f$ profile. +///
pres_scale Scale of the pressure profile. +///
psibry Value of @f$\psi@f$ at the boundary. +///
psimin Minimum @f$\psi@f$ value. +///
rmin Minimum radial value. +///
te_scale Scale of the electron temperature profile. +///
zmin Minimum vertial value. +///
1D Qantities +///
NameSize Discription +///
fpol_ci numpsi Flux function profile coefficents +///
ne_ci numpsi @f$n_{e}@f$ profile coefficents. +///
pressure_ci numpsi Pressure profile coefficents. +///
te_ci numpsi @f$t_{e}@f$ profile coefficents. +///
2D Qantities +///
NameSize Discription +///
psi_cij (numr,numz)@f$\psi\left(r,z\right)@f$ coefficents. +///
+/// +///
+/// @section equilibrum_vmec VMEC +/// @image{} html vmec.png "Cross section of 3D flux surfaces." +/// VMEC is an equilibium that comes from +/// minimizing mhd energy. +/// The solution gives us set of Fourier coefficents on a discrete radial grid. +/// 1D profiles of electrion density +/// @f$n_{e}\left(\psi\right)@f$, electron temperature +/// @f$t_{e}\left(\psi\right)@f$, and pressure @f$p\left(\psi\right)@f$ are +/// mapped as functions of the normalized flux. +/// +/// @subsection equilibrum_vmec_format VMEC file format +/// Quantities are loaded into the ray tracer via a netcdf file. VMEC NetCDF +/// files must contain the following quantities. Spline quanities have a common +/// format of name_ci. All radial quantities are splined accross +/// the magnetic axis to the opposite end. That is quantities extend from +/// @f$-s\rightarrow s @f$. Splines of fourier coeffients are one dimensional +/// splines stored in a 2D array. Radial quantities are stored as a full or +/// half grid value. +/// +/// +///
VMEC netcdf file quantities
Dimensions +///
Name Discription +///
numsf Size of full radial grid. +///
numsh Size of half radial grid. +///
nummn Number of Fourier modes. +///
Scalar Qantities +///
dphi Step size of toroidal flux. +///
ds Step size of normalized toroidal flux. +///
signj Sign of the Jacobian. +///
sminf Minimum @f$s @f$ on the full grid. +///
sminh Minimum @f$s @f$ on the half grid. +///
1D Qantities +///
Name Size Discription +///
chi_ci numsf Poloidal flux profile. +///
xm nummn Poloidal modes. +///
xn nummn Toroidal modes. +///
2D Qantities +///
Name Size Discription +///
lmns_ci (numsh,nummn)@f$\lambda @f$ fourier coefficents. +///
rmnc_ci (numsf,nummn)@f$r @f$ fourier coefficents. +///
zmns_ci (numsf,nummn)@f$z @f$ fourier coefficents. +///
+/// +///
+/// @section equilibrum_devel Developing new equilibrium models +/// This section is intended for code developers and outlines how to create new +/// equilibrium models. All equilibrium model use the same +/// @ref equilibrium::generic interface. New equilibrium models can be created +/// from a subclass of @ref equilibrium::generic or any other existing +/// equilibrium class and overloading class methods. +/// @code +/// template +/// class new_equilibrium final : public generic { +/// ... +/// }; +/// @endcode +/// +/// When a new equilibrium is +/// subclassed from @ref equilibrium::generic implimentations must be provided +/// for the following pure virtual methods. +/// * @ref equilibrium::generic::get_characteristic_field +/// * @ref equilibrium::generic::get_electron_density +/// * @ref equilibrium::generic::get_electron_temperature +/// * @ref equilibrium::generic::get_ion_density +/// * @ref equilibrium::generic::get_ion_temperature +/// * @ref equilibrium::generic::get_magnetic_field +/// +/// @note @ref equilibrium::generic::get_characteristic_field is only used by +/// the normalized boris method for particle pushing. For most cases this can +/// simply return 1. +/// +/// For the remaining methods, or any other methods one wishes to override, the +/// arguments provide expressions for the input position of the ray. The +/// methods return are expressions for the quantity at hand. +/// +/// @subsection equilibrum_devel_coordinate Noncartesian Coordinates +/// While these methods take an @f$x,y,z @f$ as the argument names, there is +/// no reason these need to be assumed to be cartesian coordinates. For +/// instance the @ref equilibrum_vmec treats @f$x,y,z\rightarrow s,u,v @f$ as +/// flux coordinates. In flux coordinate the coordinate system is no longer +/// normalized nor orthogonal. So that other parts of the code can treat +/// @f$\vec{k}@f$ correctly there are methods to return the covariant basis +/// vectors @f$\vec{e}_{s},\vec{e}_{u},\vec{e}_{v}@f$. +/// * @ref equilibrium::generic::get_esup1 +/// * @ref equilibrium::generic::get_esup2 +/// * @ref equilibrium::generic::get_esup3 +/// +/// By default, @ref equilibrium::generic return basis vectors for a cartesian +/// system @f$\vec{e}_{1}=\hat{x},\vec{e}_{2}=\hat{y},\vec{e}_{3}=\hat{z}@f$. +//------------------------------------------------------------------------------ #ifndef equilibrium_h #define equilibrium_h @@ -19,6 +220,7 @@ #include "arithmetic.hpp" #include "newton.hpp" +/// Name space for equilibrium models. namespace equilibrium { /// Lock to syncronize netcdf accross threads. static std::mutex sync; @@ -30,7 +232,7 @@ namespace equilibrium { /// @brief Class representing a generic equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class generic { @@ -162,7 +364,7 @@ namespace equilibrium { /// /// The characteristic field is equilibrium dependent. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -276,7 +478,7 @@ namespace equilibrium { /// @brief Uniform density with no magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class no_magnetic_field : public generic { @@ -376,7 +578,7 @@ namespace equilibrium { /// /// To avoid divide by zeros use the value of 1. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -389,7 +591,7 @@ namespace equilibrium { /// @brief Convenience function to build a no magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A constructed no magnetic field equilibrium. //------------------------------------------------------------------------------ @@ -405,7 +607,7 @@ namespace equilibrium { /// @brief Uniform density with varying magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class slab : public generic { @@ -500,7 +702,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -513,7 +715,7 @@ namespace equilibrium { /// @brief Convenience function to build a slab equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A constructed slab equilibrium. //------------------------------------------------------------------------------ @@ -529,7 +731,7 @@ namespace equilibrium { /// @brief Vary density with uniform magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class slab_density : public generic { @@ -629,7 +831,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -642,7 +844,7 @@ namespace equilibrium { /// @brief Convenience function to build a slab density equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A constructed slab density equilibrium. //------------------------------------------------------------------------------ @@ -658,7 +860,7 @@ namespace equilibrium { /// @brief Vary density with uniform magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class slab_field : public generic { @@ -757,7 +959,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -770,7 +972,7 @@ namespace equilibrium { /// @brief Convenience function to build a slab density equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A constructed slab density equilibrium. //------------------------------------------------------------------------------ @@ -785,7 +987,7 @@ namespace equilibrium { /// @brief Guassian density with uniform magnetic field equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class guassian_density : public generic { @@ -883,7 +1085,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -896,7 +1098,7 @@ namespace equilibrium { /// @brief Convenience function to build a guassian density equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A constructed guassian density equilibrium. //------------------------------------------------------------------------------ @@ -909,7 +1111,7 @@ namespace equilibrium { /// @brief Build a 1D spline. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] c Array of spline coeffiecents. /// @param[in] x Spline argument. @@ -936,11 +1138,11 @@ namespace equilibrium { //------------------------------------------------------------------------------ /// @brief 2D EFIT equilibrium. /// -/// This takes a BiCublic spline representation of the psi and cubic splines for -/// ne, te, p, and fpol. +/// This takes a BiCublic spline representation of the psi and cubic splines +/// for ne, te, p, and fpol. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class efit final : public generic { @@ -1378,7 +1580,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -1419,7 +1621,7 @@ namespace equilibrium { /// @brief Convenience function to build an EFIT equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] spline_file File name of contains the spline functions. /// @returns A constructed EFIT equilibrium. @@ -1662,7 +1864,7 @@ namespace equilibrium { /// This takes a Cublic spline interpolations of the vmec quantities. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class vmec final : public generic { @@ -2151,7 +2353,7 @@ namespace equilibrium { /// /// Use the value at the y intercept. /// -/// @params[in] device_number Device to use. +/// @param[in] device_number Device to use. /// @returns The characteristic field. //------------------------------------------------------------------------------ virtual graph::shared_leaf @@ -2216,7 +2418,7 @@ namespace equilibrium { /// @brief Convenience function to build an VMEC equilibrium. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] spline_file File name of contains the spline functions. /// @returns A constructed VMEC equilibrium. diff --git a/graph_framework/jit.hpp b/graph_framework/jit.hpp index 410416ac9360d1040b6a7ed95e17fc1bd8dcd055..c22bb79799c18781ea966619df64313e97d863e2 100644 --- a/graph_framework/jit.hpp +++ b/graph_framework/jit.hpp @@ -19,6 +19,16 @@ #endif #include "cpu_context.hpp" +//------------------------------------------------------------------------------ +/// @def START_GPU +/// Starts a Cocoa auto release pool when using the metal backend. No opt +/// otherwise. +//------------------------------------------------------------------------------ +//------------------------------------------------------------------------------ +/// @def END_GPU +/// Ends a Cocoa auto release pool when using the metal backend. No opt +/// otherwise. +//------------------------------------------------------------------------------ #ifdef USE_METAL #define START_GPU @autoreleasepool { #define END_GPU } @@ -27,12 +37,13 @@ #define END_GPU #endif +/// Name space for JIT functions. namespace jit { //------------------------------------------------------------------------------ /// @brief Class for JIT compile of the GPU kernels. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class context { @@ -310,7 +321,7 @@ namespace jit { } //------------------------------------------------------------------------------ -/// @brief Get buffer frim the gpu\_context. +/// @brief Get buffer from the gpu_context. /// /// @param[in] node Node to get the gpu buffer for. //------------------------------------------------------------------------------ diff --git a/graph_framework/math.hpp b/graph_framework/math.hpp index 9568ca5b3e45e0bf347c77fdcfc224dcc915682c..9ef8dc1e622e309edf73e3af419083027ecb5029 100644 --- a/graph_framework/math.hpp +++ b/graph_framework/math.hpp @@ -20,7 +20,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class sqrt_node final : public straight_node { @@ -190,9 +190,9 @@ namespace graph { auto x_cast = sqrt_cast(x); if (x_cast.get()) { return this->arg->is_match(x_cast->get_arg()); - } else { - return false; } + + return false; } //------------------------------------------------------------------------------ @@ -270,7 +270,7 @@ namespace graph { /// @brief Define sqrt convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced sqrt node. @@ -304,7 +304,7 @@ namespace graph { /// @brief Cast to a sqrt node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -323,7 +323,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class exp_node final : public straight_node { @@ -535,7 +535,7 @@ namespace graph { /// @brief Define exp convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced exp node. @@ -569,7 +569,7 @@ namespace graph { /// @brief Cast to a exp node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -586,7 +586,7 @@ namespace graph { /// @brief A log node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// Note use templates here to defer this so it can use the operator functions. //------------------------------------------------------------------------------ @@ -778,7 +778,7 @@ namespace graph { /// @brief Define log convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced log node. @@ -811,7 +811,7 @@ namespace graph { /// @brief Cast to a exp node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -830,7 +830,7 @@ namespace graph { /// Note use templates here to defer this so it can use the operator functions. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class pow_node final : public branch_node { @@ -1343,7 +1343,7 @@ namespace graph { /// @brief Build power node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1375,7 +1375,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1391,7 +1391,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -1424,7 +1424,7 @@ namespace graph { /// @brief An imaginary error function node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// Note use templates here to defer this so it can use the operator functions. //------------------------------------------------------------------------------ @@ -1611,7 +1611,7 @@ namespace graph { /// @brief Define erfi convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced exp node. @@ -1645,7 +1645,7 @@ namespace graph { /// @brief Cast to a exp node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. diff --git a/graph_framework/metal_context.hpp b/graph_framework/metal_context.hpp index d85ea9f1ff832b4457c3272c26af2106fdec47b8..c5c980d6c3d33244f273d5bddee62af9f77fe025 100644 --- a/graph_framework/metal_context.hpp +++ b/graph_framework/metal_context.hpp @@ -14,11 +14,12 @@ #include "random.hpp" +/// Name space for GPU backends. namespace gpu { //------------------------------------------------------------------------------ /// @brief Class representing a metal gpu context. /// -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class metal_context { @@ -395,7 +396,6 @@ namespace gpu { const size_t size = [kernel_arguments[node.get()] length]; memcpy([kernel_arguments[node.get()] contents], source, size); - [kernel_arguments[node.get()] didModifyRange:NSMakeRange(0, size)]; } //------------------------------------------------------------------------------ diff --git a/graph_framework/newton.hpp b/graph_framework/newton.hpp index 92008710eedaeaf262e4efd3f8afdd848b33c01f..9f1cbb4bca9d81133eb91592d701ed77ddcc718a 100644 --- a/graph_framework/newton.hpp +++ b/graph_framework/newton.hpp @@ -17,7 +17,7 @@ namespace solver { /// This uses newtons methods to solver for D(x) = 0. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in,out] work Workflow manager. /// @param[in] vars The unknowns to solver for. diff --git a/graph_framework/node.hpp b/graph_framework/node.hpp index 5b236d24ac57df6c0db23c6a4a1fcdd3c73ab9c9..698a5515a090a7b935c6692d332bed590f088aa2 100644 --- a/graph_framework/node.hpp +++ b/graph_framework/node.hpp @@ -4,7 +4,340 @@ /// /// Defines a tree of operations that allows automatic differentiation. //------------------------------------------------------------------------------ - +//------------------------------------------------------------------------------ +/// @page new_operations_tutorial Adding New Operations Tutorial +/// @brief A tutorial for creating new operations. +/// @tableofcontents +/// +/// @section new_operations_tutorial_intro Introduction +/// In most cases, physics problems can be generated from combinations of graph +/// nodes. For instance, the @ref graph::tan nodes are built from +/// @f$\frac{\sin\left(x\right)}{\cos\left(x\right)}@f$. However, some problems +/// will call for adding new operations. This page provides a basic example of +/// how to impliment a new operator @f$foo\left(x\right)@f$ in the +/// graph_framework. +/// +///
+/// @section new_operations_tutorial_node_subclass Node Subclasses +/// All graph nodes are subclasses of @ref graph::leaf_node or subclasses of +/// other nodes. In the case of our @f$foo\left(x\right)@f$ example we can +/// sublass the @ref graph::straight_node since these assume single arguments. +/// If there are two or three operands you can subclass +/// * @ref graph::branch_node +/// * @ref graph::triple_node +/// +/// @note Any existing node can be subclassed but do so with caution. +/// Subclasses inherent reduction rules which maybe incorrect. +/// +/// In this case, the @ref graph::straight_node (Along with +/// @ref graph::branch_node, @ref graph::triple_node) have no reduction +/// assumputions. For this case since our operation @f$foo\left(x\right)@f$ +/// takes one argument, we will subclass the @ref graph::straight_node. +/// +/// The basics of subclassing a node, start with a subclass and a constructor. +/// @code +/// template +/// class foo_node : public straight_node { +/// private: +/// static std::string to_string(leaf_node *x) { +/// return "foo(" + +/// jit::format_to_string(reinterpret_cast (l)) + +/// ")"; +/// } +/// +/// public: +/// foo_node(shared_leaf x) : +/// straight_node(x, foo_node::to_string(x.get())) {} +/// }; +/// @endcode +/// The static to_string method provices an idenifier that can be used +/// to generate a hash for the node. This hash will be used later in a factory +/// function to exsure nodes only exist once. +/// +/// A factory function constructs a node then immedately reduces it. The +/// reduced node is then checked if it already exists in the +/// @ref graph::leaf_node::caches_t::nodes. If the node is a new node, we add +/// it to the cache and return it. Otherwise we discard the node and return the +/// cached node in it's place. +/// @code +/// template +/// shared_leaf foo(shared_leaf x) { +/// auto temp = std::make_shared> (x)->reduce(); +/// // Test for hash collisions. +/// for (size_t i = temp->get_hash(); +/// i < std::numeric_limits::max(); i++) { +/// if (leaf_node::caches.nodes.find(i) == +/// leaf_node::caches.nodes.end()) { +/// leaf_node::caches.nodes[i] = temp; +/// return temp; +/// } else if (temp->is_match(leaf_node::caches.nodes[i])) { +/// return leaf_node::caches.nodes[i]; +/// } +/// } +/// } +/// @endcode +/// +/// To aid in introspection we also need a function to cast a generic +/// @ref graph::shared_leaf back to the specific node type. For convience, we +/// also define a type alias for shared type. +/// @code +/// template +/// using shared_foo = std::shared_ptr>; +/// +/// template +/// shared_foo foo_cast(shared_leaf x) { +/// return std::dynamic_pointer_cast> (x); +/// } +/// @endcode +/// +///
+/// @section new_operations_tutorial_method Methods overloads +/// To subclass a @ref graph::leaf_node there are several methods that need to +/// be provided. +/// +///
+/// @subsection new_operations_tutorial_evalute Evaluate +/// To start, lets provide a way to +/// @ref graph::leaf_node::evaluate "evalute the node". The first step to +/// evaluate a node is to evaluate the nodes argument. +/// @code +/// virtual shared_leaf evaluate() { +/// backend::buffer result = this->arg->evaluate(); +/// } +/// @endcode +/// @ref backend::buffer are quick ways we can evalute the node on the host +/// before needing to generate device kernels and is used by the +/// @ref graph::leaf_node::reduce method to precompute constant values. We can +/// extend the @ref backend::buffer class with a new method to evaluate foo or +/// you can use the existing operators. In this case lets assume +/// @f$foo\left(x\right)=x^{2}@f$. +/// @code +/// virtual shared_leaf evaluate() { +/// backend::buffer result = this->arg->evaluate(); +/// return result*result; +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_is_match Is Match +/// This methiod checks if the node matches another node. The first thing to +/// check is if the pointers match. Then we can check if the structure of the +/// graphs match. This is important for the factory function. When checking for +/// cached nodes, two graphs can be identical but have different pointer +/// values. Checking the structure of the graphs ensures that we catch +/// identical graphs. +/// @code +/// virtual bool is_match(shared_leaf x) { +/// if (this == x.get()) { +/// return true; +/// } +/// +/// auto x_cast = foo_cast(x); +/// if (x_cast.get()) { +/// return this->arg->is_match(x_cast->get_arg()); +/// } +/// +/// return false; +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_reduce Reduce +/// Lets add a simple reduction method. When the argument @f$x @f$ is a +/// constant we can reduce this node down to a single constant by pre +/// evaluating it. +/// @code +/// virtual shared_leaf reduce() { +/// if (constant_cast(this->arg).get()) { +/// return constant (this->evaluate()); +/// } +/// +/// return this->shared_from_this(); +/// } +/// @endcode +/// In this example we first check if the argument can be cast to a constant. +/// If it was castable, we evalute this node and create a new constant to +/// return in its place. Otherwise we return the current node unchanged. +/// @note Other reductions are possible but not shown here. +/// +///
+/// @subsection new_operations_tutorial_df df +/// Auto differentiation is provided by returning the derivative expression. +/// @f$\frac{\partial}{\partial y}foo\left(x\right)=2x\frac{\partial x}{\partial y}@f$. +/// However, in this framework it is also possible to take a derivative with +/// respect to itself @f$\frac{\partial foo\left(x\right)}{\partial foo\left(x\right)}=1 @f$. +/// @code +/// virtual shared_leaf df(shared_leaf x) { +/// if (this->is_match(x)) { +/// return one (); +/// } +/// +/// const size_t hash = reinterpret_cast (x.get()); +/// if (this->df_cache.find(hash) == this->df_cache.end()) { +/// this->df_cache[hash] = 2.0*this->arg*this->arg->df(x); +/// } +/// return this->df_cache[hash]; +/// } +/// @endcode +/// Here we made use of the @ref graph::leaf_node::df_cache to avoid needing +/// to rebuild expressions everytime the same derivative is taken. +/// +///
+/// @subsection new_operations_tutorial_compile_preamble Compile preamble +/// The @ref graph::leaf_node::compile_preamble method provides ways to include +/// header files or define functions. Lets use this method to define a function +/// that can be called from the kernel. +/// @code +/// virtual void compile_preamble(std::ostringstream &stream, +/// jit::register_map ®isters, +/// jit::visiter_map &visited, +/// jit::register_usage &usage, +/// jit::texture1d_list &textures1d, +/// jit::texture2d_list &textures2d, +/// int &avail_const_mem) { +/// if (visited.find(this) == visited.end()) { +/// this->arg->compile_preamble(stream, registers, +/// visited, usage, +/// textures1d, textures2d, +/// avail_const_mem); +/// +/// jit::add_type (stream); +/// stream << " foo(const " +/// jit::add_type (stream); +/// stream << "x) {" +/// << " return 2*x;" +/// << "}"; +/// +/// visited.insert(this); +/// #ifdef SHOW_USE_COUNT +/// usage[this] = 1; +/// } else { +/// ++usage[this]; +/// #endif +/// } +/// } +/// @endcode +/// The compile methods generate kernel source code. In this case we created a +/// function in the preamble to evaluate foo. Since we only want this create +/// this preamble once, we first check if this node has already been visited. +/// The @ref build_system_dev_options "build system option" +/// SHOW_USE_COUNT tracks the number of times a node is used in the +/// kernel. When this option is set we need to increment it's usage count. +/// @note Most nodes don't require a preamble so this method can be left out. +/// +///
+/// @subsection new_operations_tutorial_compile Compile +/// The compile method writes a line of source code to the kernel. Here we can +/// use the function defined in the preamble. +/// @code +/// virtual shared_leaf +/// compile(std::ostringstream &stream, +/// jit::register_map ®isters, +/// jit::register_map &indices, +/// const jit::register_usage &usage) { +/// if (registers.find(this) == registers.end()) { +/// shared_leaf a = this->arg->compile(stream, +/// registers, +/// indices, +/// usage); +/// +/// registers[this] = jit::to_string('r', this); +/// stream << " const "; +/// jit::add_type (stream); +/// stream << " " << registers[this] << " = foo(" +/// << registers[a.get()] << ")"; +/// this->endline(stream, usage); +/// } +/// +/// return this->shared_from_this(); +/// } +/// @endcode +/// Kernels are created by assuming infinite registers. In this case, a +/// register is a temporary variable. To provide a unquie name, the node +/// pointer value is converted into a string. Since we only want to evaluate +/// this once, we check if the register has already been created. +/// +///
+/// @subsection new_operations_tutorial_to_latex To Latex +/// This method returns the code to generate the @f$\LaTeX @f$ expression for +/// the node. +/// @code +/// virtual void to_latex () const { +/// std::cout << "foo\left(; +/// this->arg->to_latex(); +/// std::cout << "\right)"; +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_is_power_like Is Power Like +/// This provides information for other nodes about how this works for +/// reduction methods. In this care we need to set this to true. If this node +/// did not act like a power, this method can be ignored. +/// @code +/// virtual bool is_power_like() const { +/// return true; +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_get_power_base Get power base +/// Return the base of the power node. This provides information for other +/// nodes about how this works for reduction methods. In this case the power +/// base is the function argument. +/// @code +/// virtual shared_leaf get_power_base() const { +/// return this->arg; +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_get_power_exponent Get power exponent +/// Return the exponent of the power node. This provides information for other +/// nodes about how this works for reduction methods. In this case, the power +/// exponent is @f$2 @f$. +/// @code +/// virtual shared_leaf get_power_exponent() const { +/// return constant (static_cast (2.0)); +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_remove_pseudo Remove Pseudo +/// Return the node with pseduo variables removed. +/// @ref graph::pseudo_variable_node are used to end derivatives construction +/// by treating a sub graph as a pseduo variable. Before graphs can be +/// evaluated, these @ref graph::pseudo_variable_node need to be removed. +/// @code +/// virtual shared_leaf remove_pseudo() { +/// if (this->has_pseudo()) { +/// return sqrt(this->arg->remove_pseudo()); +/// } +/// return this->shared_from_this(); +/// } +/// @endcode +/// +///
+/// @subsection new_operations_tutorial_to_vizgraph To Vizgraph +/// Generates a vizgraph node for +/// visualization. +/// @code +/// virtual shared_leaf to_vizgraph(std::stringstream &stream, +/// jit::register_map ®isters) { +/// if (registers.find(this) == registers.end()) { +/// const std::string name = jit::to_string('r', this); +/// registers[this] = name; +/// stream << " " << name +/// << " [label = \"foo\", shape = oval, style = filled, fillcolor = blue, fontcolor = white];" << std::endl; +/// +/// auto a = this->arg->to_vizgraph(stream, registers); +/// stream << " " << name << " -- " << registers[a.get()] << ";" << std::endl; +/// } +/// +/// return this->shared_from_this(); +/// } +/// @endcode +//------------------------------------------------------------------------------ #ifndef node_h #define node_h @@ -16,6 +349,7 @@ #include "backend.hpp" +/// Name space for graph nodes. namespace graph { //****************************************************************************** // Base leaf node. @@ -24,7 +358,7 @@ namespace graph { /// @brief Class representing a node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class leaf_node : public std::enable_shared_from_this> { @@ -133,7 +467,9 @@ namespace graph { /// @param[in] x Other graph to check if it is a match. /// @returns True if the nodes are a match. //------------------------------------------------------------------------------ - virtual bool is_match(std::shared_ptr> x) = 0; + virtual bool is_match(std::shared_ptr> x) { + return this == x.get(); + } //------------------------------------------------------------------------------ /// @brief Check if the base of the powers match. @@ -339,7 +675,7 @@ namespace graph { /// @brief Create a null leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A null leaf. //------------------------------------------------------------------------------ @@ -384,7 +720,7 @@ namespace graph { /// @brief Class representing data that cannot change. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class constant_node final : public leaf_node { @@ -606,7 +942,7 @@ namespace graph { /// @brief Construct a constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Array buffer. /// @returns A reduced constant node. @@ -635,7 +971,7 @@ namespace graph { /// @brief Construct a constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Scalar data to initalize. /// @returns A reduced constant node. @@ -650,7 +986,7 @@ namespace graph { /// @brief Create a zero constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A zero constant. //------------------------------------------------------------------------------ @@ -663,7 +999,7 @@ namespace graph { /// @brief Create a one constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A one constant. //------------------------------------------------------------------------------ @@ -676,7 +1012,7 @@ namespace graph { /// @brief Create a one constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A one constant. //------------------------------------------------------------------------------ @@ -697,7 +1033,7 @@ namespace graph { /// @brief Cast to a constant node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -714,7 +1050,7 @@ namespace graph { /// @brief Class representing a straight node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// This ensures that the base leaf type has the common type between the two /// template arguments. @@ -828,7 +1164,7 @@ namespace graph { /// @brief Class representing a branch node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// This ensures that the base leaf type has the common type between the two /// template arguments. @@ -836,9 +1172,9 @@ namespace graph { template class branch_node : public leaf_node { protected: -// Left branch of the tree. +/// Left branch of the tree. shared_leaf left; -// Right branch of the tree. +/// Right branch of the tree. shared_leaf right; public: @@ -952,7 +1288,7 @@ namespace graph { /// @brief Class representing a triple branch node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// This ensures that the base leaf type has the common type between the two /// template arguments. @@ -960,7 +1296,7 @@ namespace graph { template class triple_node : public branch_node { protected: -// Middle branch of the tree. +/// Middle branch of the tree. shared_leaf middle; public: @@ -1052,7 +1388,7 @@ namespace graph { /// @brief Class representing data that can change. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class variable_node final : public leaf_node { @@ -1201,16 +1537,6 @@ namespace graph { return this->shared_from_this(); } -//------------------------------------------------------------------------------ -/// @brief Querey if the nodes match. -/// -/// @param[in] x Other graph to check if it is a match. -/// @returns True if the nodes are a match. -//------------------------------------------------------------------------------ - virtual bool is_match(shared_leaf x) { - return this == x.get(); - } - //------------------------------------------------------------------------------ /// @brief Set the value of variable data. /// @@ -1339,7 +1665,7 @@ namespace graph { /// @brief Construct a variable. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] s Size of the data buffer. /// @param[in] symbol Symbol of the variable used in equations. @@ -1354,7 +1680,7 @@ namespace graph { /// @brief Construct a variable. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] s Size of he data buffer. /// @param[in] d Scalar data to initalize. @@ -1370,7 +1696,7 @@ namespace graph { /// @brief Construct a variable. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Array buffer. /// @param[in] symbol Symbol of the variable used in equations. @@ -1385,7 +1711,7 @@ namespace graph { /// @brief Construct a variable. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Array buffer. /// @param[in] symbol Symbol of the variable used in equations. @@ -1411,7 +1737,7 @@ namespace graph { /// @brief Cast to a variable node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -1432,7 +1758,7 @@ namespace graph { /// something that is not itself. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class pseudo_variable_node final : public straight_node { @@ -1477,16 +1803,6 @@ namespace graph { return constant (static_cast (this->is_match(x))); } -//------------------------------------------------------------------------------ -/// @brief Querey if the nodes match. -/// -/// @param[in] x Other graph to check if it is a match. -/// @returns True if the nodes are a match. -//------------------------------------------------------------------------------ - virtual bool is_match(shared_leaf x) { - return this == x.get(); - } - //------------------------------------------------------------------------------ /// @brief Convert the node to latex. //------------------------------------------------------------------------------ @@ -1577,7 +1893,7 @@ namespace graph { /// @brief Define pseudo variable convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced pseudo variable node. @@ -1595,7 +1911,7 @@ namespace graph { /// @brief Cast to a pseudo variable node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. diff --git a/graph_framework/output.hpp b/graph_framework/output.hpp index a09cd9e64c8ceef3fb419eb70d7b37c832342a37..4b7184fbda58c5645115ebad25e7f8c580ea18c8 100644 --- a/graph_framework/output.hpp +++ b/graph_framework/output.hpp @@ -12,6 +12,7 @@ #include "jit.hpp" +/// Name space for output files. namespace output { /// Lock to syncronize netcdf accross threads. static std::mutex sync; @@ -248,7 +249,7 @@ namespace output { //------------------------------------------------------------------------------ /// @brief Create a variable. /// -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] result A result file reference. /// @param[in] name Name of the variable. @@ -274,7 +275,7 @@ namespace output { //------------------------------------------------------------------------------ /// @brief Load reference. /// -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] result A result file reference. /// @param[in] name Name of the variable. @@ -310,7 +311,7 @@ namespace output { //------------------------------------------------------------------------------ /// @brief Load imaginary reference. /// -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] result A result file reference. /// @param[in] name Name of the variable. diff --git a/graph_framework/piecewise.hpp b/graph_framework/piecewise.hpp index de735f478632a9138ca73cdc4675525d568bad02..811c4e26b383cdf9e8d923967afa11ec079d9bd3 100644 --- a/graph_framework/piecewise.hpp +++ b/graph_framework/piecewise.hpp @@ -86,7 +86,7 @@ void compile_index(std::ostringstream &stream, /// x_norm' = (x - xmin)/dx (11) /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class piecewise_1D_node final : public straight_node { @@ -548,16 +548,16 @@ void compile_index(std::ostringstream &stream, }; //------------------------------------------------------------------------------ -/// @brief Define piecewise\_1D convience function. +/// @brief Define piecewise_1D convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Data to initalize the piecewise constant. /// @param[in] x Argument. /// @param[in] scale Argument scale factor. /// @param[in] offset Argument offset factor. -/// @returns A reduced piecewise\_1D node. +/// @returns A reduced piecewise_1D node. //------------------------------------------------------------------------------ template shared_leaf piecewise_1D(const backend::buffer &d, @@ -592,7 +592,7 @@ void compile_index(std::ostringstream &stream, /// @brief Cast to a piecewise 1D node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -644,7 +644,7 @@ void compile_index(std::ostringstream &stream, /// y_norm' = (y - ymin)/dy (21) /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class piecewise_2D_node final : public branch_node { @@ -1262,10 +1262,10 @@ void compile_index(std::ostringstream &stream, }; //------------------------------------------------------------------------------ -/// @brief Define piecewise\_2D convience function. +/// @brief Define piecewise_2D convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] d Data to initalize the piecewise constant. /// @param[in] n Number of columns. @@ -1314,7 +1314,7 @@ void compile_index(std::ostringstream &stream, /// @brief Cast to a piecewise 2D node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. diff --git a/graph_framework/random.hpp b/graph_framework/random.hpp index 1d0cb883ceb29d3b2c34e52982f017cf9dafb7f4..ace6faa485f8eb67d509dbd1c0482d6ac6235418 100644 --- a/graph_framework/random.hpp +++ b/graph_framework/random.hpp @@ -18,7 +18,7 @@ namespace graph { /// @brief Class representing a random_state_node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class random_state_node final : public leaf_node { @@ -32,6 +32,7 @@ namespace graph { /// State index. uint16_t index; #ifdef USE_CUDA +/// Pading to aline the size of the struct for Cuda backends. uint16_t padding[3]; #endif }; @@ -39,6 +40,7 @@ namespace graph { //------------------------------------------------------------------------------ /// @brief Construct a constant node from a vector. /// +/// @param[in] size Number of random states. /// @param[in] seed Inital random seed. //------------------------------------------------------------------------------ random_state_node(const size_t size, @@ -104,7 +106,10 @@ namespace graph { << " uint16_t padding[3];" << std::endl #endif << "};" << std::endl; + + visited.insert(this); #ifdef SHOW_USE_COUNT + usage[this] = 1; } else { ++usage[this]; #endif @@ -128,19 +133,6 @@ namespace graph { return this->shared_from_this(); } -//------------------------------------------------------------------------------ -/// @brief Querey if the nodes match. -/// -/// @param[in] x Other graph to check if it is a match. -/// @returns True if the nodes are a match. -//------------------------------------------------------------------------------ - virtual bool is_match(shared_leaf x) { - if (this == x.get()) { - return true; - } - return false; - } - //------------------------------------------------------------------------------ /// @brief Convert the node to latex. //------------------------------------------------------------------------------ @@ -247,7 +239,7 @@ namespace graph { /// @brief Define random_state convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] size Number of random states. /// @param[in] seed Inital random seed. @@ -283,7 +275,7 @@ namespace graph { /// @brief Cast to a random_state node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -300,7 +292,7 @@ namespace graph { /// @brief Class representing a random_node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class random_node final : public straight_node { @@ -373,12 +365,12 @@ namespace graph { jit::texture1d_list &textures1d, jit::texture2d_list &textures2d, int &avail_const_mem) { - this->arg->compile_preamble(stream, registers, - visited, usage, - textures1d, textures2d, - avail_const_mem); - if (visited.find(this) == visited.end()) { + this->arg->compile_preamble(stream, registers, + visited, usage, + textures1d, textures2d, + avail_const_mem); + jit::add_type (stream); stream << " random("; if constexpr (jit::use_metal ()) { @@ -404,7 +396,10 @@ namespace graph { jit::add_type (stream); stream << "> (y^(y >> 18));" << std::endl << "}" << std::endl; + + visited.insert(this); #ifdef SHOW_USE_COUNT + usage[this] = 1; } else { ++usage[this]; #endif @@ -504,7 +499,7 @@ namespace graph { /// @brief Define random convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] state Random state node. /// @returns A reduced random node. @@ -538,7 +533,7 @@ namespace graph { /// @brief Cast to a random node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -552,7 +547,7 @@ namespace graph { /// @brief Create a random_scale constant. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @returns A random_scale constant. //------------------------------------------------------------------------------ diff --git a/graph_framework/register.hpp b/graph_framework/register.hpp index 22014518c97b7358410e67759b1f39929619fa15..8daaa20d4503712ed2470b689ba7cc75e2ea2ef0 100644 --- a/graph_framework/register.hpp +++ b/graph_framework/register.hpp @@ -227,17 +227,18 @@ namespace jit { } //------------------------------------------------------------------------------ -/// @brief Convert a leaf\_node pointer to a string. +/// @brief Convert a @ref graph::leaf_node pointer to a string. /// -/// This converts the point value into a string of format t\_######. Where t is +/// This converts the point value into a string of format t######. Where t is /// of type /// -# v Variable /// -# r Register +/// -# i Input /// /// @tparam NODE Node class type. /// /// @param[in] prefix Type prefix for the name. -/// @param[in] pointer Address of the @ref{leaf_node}. +/// @param[in] pointer Address of the @ref graph::leaf_node. /// @returns The pointer value as a string. //------------------------------------------------------------------------------ template diff --git a/graph_framework/solver.hpp b/graph_framework/solver.hpp index bc08407dbb7a84b2cbd35a2cf215a862e5b8916c..122d853eb035240f872738116c955c9726bab8ed 100644 --- a/graph_framework/solver.hpp +++ b/graph_framework/solver.hpp @@ -2,9 +2,105 @@ /// @file solver.hpp /// @brief Base class for a ode solvers. /// -/// Defines a ode solver. +/// Defines an ode solver. +//------------------------------------------------------------------------------ +//------------------------------------------------------------------------------ +/// @page solvers Solvers +/// @brief A discription of the integation methods for solving the ray equations. +/// @tableofcontents +/// +/// @section solvers_intro Introduction +/// This page documents the types of solver methods available. These solvers +/// integrate the +/// @ref dispersion_function_wave_propagation "wave propagation equations" to +/// solve for the ray trajectory. Each solver builds expressions for the +/// updates to @f$\vec{x}@f$ and @f$\vec{k}@f$. These expressions are used to +/// build @ref general_concepts_compile_maps "map" kernels that can be iterated +/// to integrate the ray equations. Available integrators are: +/// +///
+/// @subsection solvers_split_simplextic Split Simplextic +/// This solver only works when the system is separable. The conditions for +/// separability are +/// @f$\frac{\partial\frac{\partial D}{\partial\vec{k}}}{\partial\vec{k}}\equiv 0 @f$ +/// and +/// @f$\frac{\partial\frac{\partial D}{\partial\vec{x}}}{\partial\vec{x}}\equiv 0 @f$ +/// If the equations are separable, the solver proceeds as +/// @f{equation}{\vec{x}_{h}=\vec{x}+\frac{dt}{2}\frac{\partial\vec{x}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f} +/// Where @f$\frac{\partial\vec{x}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f$ +/// represents the equation of motion evaluated at the current @f$\vec{x}@f$ +/// and @f$\vec{k}@f$. Using the half step @f$\vec{x}_{h}@f$ we can update +/// @f$\vec{k}@f$. +/// @f{equation}{\vec{k}_{next}=k+dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x}_{h},\vec{k},\omega\right)@f} +/// Then we can take the remaining half step to update @f$\vec{x}@f$. +/// @f{equation}{\vec{x}_{next}=\vec{x}_{h}+\frac{dt}{2}\frac{\partial\vec{x}}{\partial t}\left(\vec{x}_{h},\vec{k}_{next},\omega\right)@f} +/// +///
+/// @subsection solvers_rk2 2nd Order Runge Kutta +/// This solver integates coupled differential equations using the Runge Kutta +/// to second order. +/// It starts by computing a substep for @f$\vec{x}@f$ and @f$\vec{k}@f$. +/// @f{equation}{\vec{x}_{1}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f} +/// @f{equation}{\vec{k}_{1}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f} +/// That substep is used to compute a second substep. +/// @f{equation}{\vec{x}_{2}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x} + \vec{x}_{1},\vec{k} + \vec{k}_{1},\omega\right)@f} +/// @f{equation}{\vec{k}_{2}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x} + \vec{x}_{1},\vec{k} + \vec{k}_{1},\omega\right)@f} +/// These substeps are combined into a single step update. +/// @f{equation}{\vec{x}_{next}=\vec{x}+\frac{\vec{x}_{1}+\vec{x}_{2}}{2}@f} +/// @f{equation}{\vec{k}_{next}=\vec{k}+\frac{\vec{k}_{1}+\vec{k}_{2}}{2}@f} +/// +///
+/// @subsection solvers_rk4 4th Order Runge Kutta +/// This solver integates coupled differential equations using the Runge Kutta +/// to fouth order. Like the second order Runge Kutta, this solver computes 4 +/// substeps. +/// @f{equation}{\vec{x}_{1}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f} +/// @f{equation}{\vec{k}_{1}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x},\vec{k},\omega\right)@f} +/// @f{equation}{\vec{x}_{2}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x} + \frac{\vec{x}_{1}}{2},\vec{k} + \frac{\vec{k}_{1}}{2},\omega\right)@f} +/// @f{equation}{\vec{k}_{2}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x} + \frac{\vec{x}_{1}}{2},\vec{k} + \frac{\vec{k}_{1}}{2},\omega\right)@f} +/// @f{equation}{\vec{x}_{3}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x} + \frac{\vec{x}_{2}}{2},\vec{k} + \frac{\vec{k}_{2}}{2},\omega\right)@f} +/// @f{equation}{\vec{k}_{3}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x} + \frac{\vec{x}_{2}}{2},\vec{k} + \frac{\vec{k}_{2}}{2},\omega\right)@f} +/// @f{equation}{\vec{x}_{4}=dt\frac{\partial\vec{x}}{\partial t}\left(\vec{x} + \vec{x}_{3},\vec{k} + \vec{k}_{3},\omega\right)@f} +/// @f{equation}{\vec{k}_{4}=dt\frac{\partial\vec{k}}{\partial t}\left(\vec{x} + \vec{x}_{3},\vec{k} + \vec{k}_{3},\omega\right)@f} +/// These substeps are combined into a single step update. +/// @f{equation}{\vec{x}_{next}=\vec{x}+\frac{\vec{x}_{1}+2\left(\vec{x}_{2}+\vec{x}_{3}\right)+\vec{x}_{4}}{6}@f} +/// @f{equation}{\vec{k}_{next}=\vec{k}+\frac{\vec{k}_{1}+2\left(\vec{k}_{2}+\vec{x}_{3}\right)+\vec{x}_{4}}{6}@f} +/// +///
+/// @subsection solvers_adaptive_rk4 Adaptive 4th Order Runge Kutta +/// This method is an extension of the 4th Order Runge Kutta which adapts the +/// step size to the solutions error. We define a loss function +/// @f{equation}{f_{loss}\left(dt,\lambda\right)=\frac{1}{dt}-\lambda D^{2}@f} +/// We use a newton method to solve for @f$dt @f$ and @f$\lambda @f$ which +/// minimize @f$f_{loss}@f$. The new @f$dt @f$ is then used in a standard 4th +/// Order Runge Kutta iteration. +/// +///
+/// @section solvers_devel Developing new solvers +/// This section is intended for code developers and outlines how to create new +/// solver methods. All solvers use the same @ref solver::solver_interface +/// interface. New solver models can be created from a subclass of +/// @ref solver::solver_interface or any other existing solver class and +/// overloading class methods. +/// @code +/// tempate +/// class new_solver : public solver_interface { +/// ... +/// } +/// @endcode +/// When a new solver method is subclassed from +/// @ref solver::solver_interface no methods need to be overloaded, Instead +/// expressions for +/// * @ref solver::solver_interface::kx_next +/// * @ref solver::solver_interface::ky_next +/// * @ref solver::solver_interface::kz_next +/// * @ref solver::solver_interface::x_next +/// * @ref solver::solver_interface::y_next +/// * @ref solver::solver_interface::z_next +/// * @ref solver::solver_interface::t_next +/// +/// must be created. //------------------------------------------------------------------------------ - #ifndef solver_h #define solver_h @@ -13,6 +109,7 @@ #include "dispersion.hpp" #include "output.hpp" +/// Name space for solvers. namespace solver { //****************************************************************************** // Solver interface. @@ -384,7 +481,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the x\_next. +/// @brief Print out the latex expression for the x_next. //------------------------------------------------------------------------------ void print_x_next() { x_next->to_latex(); @@ -392,7 +489,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the y\_next. +/// @brief Print out the latex expression for the y_next. //------------------------------------------------------------------------------ void print_y_next() { y_next->to_latex(); @@ -400,7 +497,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the z\_next. +/// @brief Print out the latex expression for the z_next. //------------------------------------------------------------------------------ void print_z_next() { z_next->to_latex(); @@ -408,7 +505,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the kx\_next. +/// @brief Print out the latex expression for the kx_next. //------------------------------------------------------------------------------ void print_kx_next() { kx_next->to_latex(); @@ -416,7 +513,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the ky\_next. +/// @brief Print out the latex expression for the ky_next. //------------------------------------------------------------------------------ void print_ky_next() { ky_next->to_latex(); @@ -424,7 +521,7 @@ namespace solver { } //------------------------------------------------------------------------------ -/// @brief Print out the latex expression for the kz\_next. +/// @brief Print out the latex expression for the kz_next. //------------------------------------------------------------------------------ void print_kz_next() { kz_next->to_latex(); diff --git a/graph_framework/special_functions.hpp b/graph_framework/special_functions.hpp index 72c0c86223a6310777bec52610bf5c2c2af3c998..3350770cdf329ffe96389630156f43055b39271e 100644 --- a/graph_framework/special_functions.hpp +++ b/graph_framework/special_functions.hpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file special\_functions.hpp +/// @file special_functions.hpp /// @brief Implimentations for special functions. /// /// Special functions are adapted from http://ab-initio.mit.edu/Faddeeva @@ -13,6 +13,7 @@ using namespace cuda::std; +/// Type alias for cuda complex types. template using complex_type = complex; @@ -26,6 +27,7 @@ using complex_type = complex; using namespace std; +/// Type alias for complex types. #if __cplusplus >= 202002L template #else @@ -35,6 +37,7 @@ using complex_type = std::complex; #endif +/// Name space for special functions. namespace special { /// I constant. diff --git a/graph_framework/timing.hpp b/graph_framework/timing.hpp index 565dad48fda2009a25d717678fa80ccbce03d47e..5303dbc0cd23aba4236b6530cefe9c8f44fec78d 100644 --- a/graph_framework/timing.hpp +++ b/graph_framework/timing.hpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file tming.hpp +/// @file timing.hpp /// @brief Routines to time the ray execution. //------------------------------------------------------------------------------ @@ -10,7 +10,8 @@ #include #include -namespace timeing { +/// Name space for timers. +namespace timing { //------------------------------------------------------------------------------ /// @brief A timing object. //------------------------------------------------------------------------------ @@ -60,6 +61,9 @@ namespace timeing { } }; +//------------------------------------------------------------------------------ +/// @brief A timing object that averages over multiple threads. +//------------------------------------------------------------------------------ class measure_diagnostic_threaded { private: /// Discription of what is being timed. diff --git a/graph_framework/trigonometry.hpp b/graph_framework/trigonometry.hpp index 74153b681c570ace5bf43106d3340239a167d831..3cb335cddfd73e4c009e62b49d53297b4247a165 100644 --- a/graph_framework/trigonometry.hpp +++ b/graph_framework/trigonometry.hpp @@ -19,7 +19,7 @@ namespace graph { /// @brief Class representing a sine_node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class sine_node final : public straight_node { @@ -36,7 +36,7 @@ namespace graph { public: //------------------------------------------------------------------------------ -/// @brief Construct a sine\_node node. +/// @brief Construct a sine_node node. /// /// @param[in] x Argument. //------------------------------------------------------------------------------ @@ -220,7 +220,7 @@ namespace graph { /// @brief Define sine convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced sin node. @@ -253,7 +253,7 @@ namespace graph { /// @brief Cast to a sine node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -270,7 +270,7 @@ namespace graph { /// @brief Class representing a cosine_node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class cosine_node final : public straight_node { @@ -472,7 +472,7 @@ namespace graph { /// @brief Define cosine convience function. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced cos node. @@ -505,7 +505,7 @@ namespace graph { /// @brief Cast to a cosine node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. @@ -524,7 +524,7 @@ namespace graph { /// tan(x) = sin(x)/cos(x) /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Argument. /// @returns A reduced tan node. @@ -541,7 +541,7 @@ namespace graph { /// @brief Class representing a sine_node leaf. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class arctan_node final : public branch_node { @@ -561,7 +561,7 @@ namespace graph { public: //------------------------------------------------------------------------------ -/// @brief Construct a arctan\_node node. +/// @brief Construct a arctan_node node. /// /// @param[in] x Argument. /// @param[in] y Argument. @@ -793,7 +793,7 @@ namespace graph { /// @brief Build arctan node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -824,7 +824,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -840,7 +840,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left branch. /// @param[in] r Right branch. @@ -859,7 +859,7 @@ namespace graph { /// @brief Cast to a power node. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x Leaf node to attempt cast. /// @returns An attemped dynamic case. diff --git a/graph_framework/vector.hpp b/graph_framework/vector.hpp index fea3069e0cac97e01f7f7c158d0d8a6a4c391734..8702554c2da75412575a40776126afef63f7e5bb 100644 --- a/graph_framework/vector.hpp +++ b/graph_framework/vector.hpp @@ -16,7 +16,7 @@ namespace graph { /// @brief Class to represent vector quantities. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class vector_quantity : public std::enable_shared_from_this> { @@ -122,7 +122,7 @@ namespace graph { /// @brief Build a shared vector quantity. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -141,7 +141,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -160,7 +160,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam M Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -179,7 +179,7 @@ namespace graph { /// /// @tparam T Base type of the calculation. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -199,7 +199,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. /// @tparam M Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -220,7 +220,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam M Float type for the constant. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -241,7 +241,7 @@ namespace graph { /// @tparam T Base type of the calculation. /// @tparam L Float type for the constant. /// @tparam R Float type for the constant. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -260,7 +260,7 @@ namespace graph { /// @brief Build a shared vector quantity. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] x X vector component. /// @param[in] y Y vector component. @@ -280,7 +280,7 @@ namespace graph { /// @brief Addition operator. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left vector. /// @param[in] r Right vector. @@ -298,7 +298,7 @@ namespace graph { /// @brief Subtraction operator. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] l Left vector. /// @param[in] r Right vector. @@ -316,7 +316,7 @@ namespace graph { /// @brief Multiplication operator. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] s Scalar term. /// @param[in] v Vector term. @@ -334,7 +334,7 @@ namespace graph { /// @brief Division operator. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] v Vector numerator. /// @param[in] s Scalar denominator. @@ -355,7 +355,7 @@ namespace graph { /// @brief Class to represent matrix quantities. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class matrix_quantity : public std::enable_shared_from_this> { @@ -402,7 +402,7 @@ namespace graph { /// @brief Build a shared vector quantity. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. /// /// @param[in] r1 Row 1 matrix component. /// @param[in] r2 Row 2 matrix component. diff --git a/graph_framework/workflow.hpp b/graph_framework/workflow.hpp index 86dac56692e7ba7778d67af0dd8811029084d180..8412559e35398d72619d08053a6ec652c7f98c10 100644 --- a/graph_framework/workflow.hpp +++ b/graph_framework/workflow.hpp @@ -10,12 +10,13 @@ #include "jit.hpp" +/// Name space for workflows. namespace workflow { //------------------------------------------------------------------------------ /// @brief Class representing a workitem. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class work_item { @@ -78,7 +79,7 @@ namespace workflow { /// @brief Class representing a convergence workitem. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class converge_item final : public work_item { @@ -164,7 +165,7 @@ namespace workflow { /// @brief Class representing a workflow manager. /// /// @tparam T Base type of the calculation. -/// @tparam SAFE_MATH Use safe math operations. +/// @tparam SAFE_MATH Use @ref general_concepts_safe_math operations. //------------------------------------------------------------------------------ template class manager { diff --git a/graph_korc/xkorc.cpp b/graph_korc/xkorc.cpp index 845d5d27d382e686d4a81702e42a89982b85664b..c3f83c5c477ffaabdd53c8057a7b9137d45fe0d2 100644 --- a/graph_korc/xkorc.cpp +++ b/graph_korc/xkorc.cpp @@ -9,7 +9,7 @@ //------------------------------------------------------------------------------ template void run_korc() { - const timeing::measure_diagnostic t_total("Total Time"); + const timing::measure_diagnostic t_total("Total Time"); const size_t num_particles = 1000000; std::cout << "Num particles " << num_particles << std::endl; @@ -24,7 +24,7 @@ void run_korc() { threads[i] = std::thread([num_particles, batch, extra] (const size_t thread_number) -> void { const size_t local_num_particles = batch + (extra > thread_number ? 1 : 0); - const timeing::measure_diagnostic t_setup("Setup Time"); + const timing::measure_diagnostic t_setup("Setup Time"); auto eq = equilibrium::make_efit (EFIT_FILE); //auto eq = equilibrium::make_slab_density (); @@ -141,7 +141,7 @@ void run_korc() { t_setup.print(); - const timeing::measure_diagnostic t_run("Run Time"); + const timing::measure_diagnostic t_run("Run Time"); work.pre_run(); for (size_t i = 0; i < 1000000; i++) { /* sync.join(); diff --git a/graph_tests/arithmetic_test.cpp b/graph_tests/arithmetic_test.cpp index 07278e7035eb196fc3879f16817c25225375c112..422ea51837c1cbcb12c0e34082dafb12048617fe 100644 --- a/graph_tests/arithmetic_test.cpp +++ b/graph_tests/arithmetic_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file arithmetic\_test.cpp +/// @file arithmetic_test.cpp /// @brief Tests for arithmetic nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/backend_test.cpp b/graph_tests/backend_test.cpp index 372c92f51a4afef2d182b5ea400be4491233ac28..50bbabde77f0a8a4b12357b037b85a122a7f2b36 100644 --- a/graph_tests/backend_test.cpp +++ b/graph_tests/backend_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file backend\_test.cpp +/// @file backend_test.cpp /// @brief Tests for the buffer backend. //------------------------------------------------------------------------------ diff --git a/graph_tests/c_binding_test.c b/graph_tests/c_binding_test.c index 56be54f7c78f7f72e51f98daae7a3b5ab22db616..9af357f6189c7856ca5227d6d427572ccd5fc41f 100644 --- a/graph_tests/c_binding_test.c +++ b/graph_tests/c_binding_test.c @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file c_binding_test.cpp +/// @file c_binding_test.c /// @brief Tests for c bindings. //------------------------------------------------------------------------------ diff --git a/graph_tests/dispersion_test.cpp b/graph_tests/dispersion_test.cpp index 52fa7bc873bf8d3e33c9c91b086045b7a8a69233..eb8dde600196e96048d00ec411766d65ea3818ba 100644 --- a/graph_tests/dispersion_test.cpp +++ b/graph_tests/dispersion_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file dispersion\_test.cpp +/// @file dispersion_test.cpp /// @brief Tests for math nodes. //------------------------------------------------------------------------------ @@ -17,9 +17,10 @@ /// /// @tparam DISPERSION Class of dispersion function to use. /// -/// @param[in] tolarance Tolarance to solver the dispersion function to. -/// @param[in] omega Ray frequency. -/// @param[in] k_guess Inital guess for the wave number. +/// @param[in] tolarance Tolarance to solver the dispersion function to. +/// @param[in] omega Ray frequency. +/// @param[in] k_guess Inital guess for the wave number. +/// @param[in,out] eq The equilibrium. //------------------------------------------------------------------------------ template void test_solve(const typename DISPERSION::base tolarance, diff --git a/graph_tests/efit_test.cpp b/graph_tests/efit_test.cpp index 2b6d5c204444c47058e59d06df2491bb09feda95..17fe05cf2b9cfff1732389852ada0e85a58cf194 100644 --- a/graph_tests/efit_test.cpp +++ b/graph_tests/efit_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file efit\_test.cpp +/// @file efit_test.cpp /// @brief Tests for efit splines. //------------------------------------------------------------------------------ diff --git a/graph_tests/erfi_test.cpp b/graph_tests/erfi_test.cpp index 766091d3ae73a2433aa7818fcd9b1c4c5071ab24..4cc5f9e0e3910fff3a5174b9d4c060f3dc18dbd2 100644 --- a/graph_tests/erfi_test.cpp +++ b/graph_tests/erfi_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file erfi\_test.cpp +/// @file erfi_test.cpp /// @brief Tests for the buffer backend. //------------------------------------------------------------------------------ diff --git a/graph_tests/f_binding_test.f90 b/graph_tests/f_binding_test.f90 index 8fa992d7664b3ad99c4331ba0d19497c000f6d48..1c3d962155e5bf106f897a63261cf82d9d9463f3 100644 --- a/graph_tests/f_binding_test.f90 +++ b/graph_tests/f_binding_test.f90 @@ -54,7 +54,6 @@ !------------------------------------------------------------------------------- !> @brief Run float tests. !> -!> @param[in] c_type Base type of the calculation. !> @param[in] use_safe_math Use safe math. !------------------------------------------------------------------------------- SUBROUTINE run_test_float(use_safe_math) @@ -186,12 +185,12 @@ C_NULL_PTR, & 'f_binding_converge' // C_NULL_CHAR, & 1_C_LONG, 1.0E-30_C_DOUBLE, 1000_C_LONG) - CALL graph%compile() + CALL graph%compile value(1) = 10.0 CALL graph%copy_to_device(z, value) - CALL graph%pre_run() - CALL graph%run() - CALL graph%wait() + CALL graph%pre_run + CALL graph%run + CALL graph%wait CALL graph%print(0_C_LONG, (/ graph_ptr(z), graph_ptr(y) /)) CALL graph%copy_to_host(y, value) @@ -227,7 +226,6 @@ !------------------------------------------------------------------------------- !> @brief Run double tests. !> -!> @param[in] c_type Base type of the calculation. !> @param[in] use_safe_math Use safe math. !------------------------------------------------------------------------------- SUBROUTINE run_test_double(use_safe_math) @@ -359,12 +357,12 @@ C_NULL_PTR, & 'f_binding_converge' // C_NULL_CHAR, & 1_C_LONG, 1.0E-30_C_DOUBLE, 1000_C_LONG) - CALL graph%compile() + CALL graph%compile value(1) = 10.0 CALL graph%copy_to_device(z, value) - CALL graph%pre_run() - CALL graph%run() - CALL graph%wait() + CALL graph%pre_run + CALL graph%run + CALL graph%wait CALL graph%print(0_C_LONG, (/ graph_ptr(z), graph_ptr(y) /)) CALL graph%copy_to_host(y, value) @@ -400,7 +398,6 @@ !------------------------------------------------------------------------------- !> @brief Run complex float tests. !> -!> @param[in] c_type Base type of the calculation. !> @param[in] use_safe_math Use safe math. !------------------------------------------------------------------------------- SUBROUTINE run_test_complex_float(use_safe_math) @@ -536,12 +533,12 @@ C_NULL_PTR, & 'f_binding_converge' // C_NULL_CHAR, & 1_C_LONG, 1.0E-30_C_DOUBLE, 1000_C_LONG) - CALL graph%compile() + CALL graph%compile value(1) = 10.0 CALL graph%copy_to_device(z, value) - CALL graph%pre_run() - CALL graph%run() - CALL graph%wait() + CALL graph%pre_run + CALL graph%run + CALL graph%wait CALL graph%print(0_C_LONG, (/ graph_ptr(z), graph_ptr(y) /)) CALL graph%copy_to_host(y, value) @@ -584,7 +581,6 @@ !------------------------------------------------------------------------------- !> @brief Run double tests. !> -!> @param[in] c_type Base type of the calculation. !> @param[in] use_safe_math Use safe math. !------------------------------------------------------------------------------- SUBROUTINE run_test_complex_double(use_safe_math) @@ -731,12 +727,12 @@ C_NULL_PTR, & 'f_binding_converge' // C_NULL_CHAR, & 1_C_LONG, 1.0E-30_C_DOUBLE, 1000_C_LONG) - CALL graph%compile() + CALL graph%compile value(1) = 10.0 CALL graph%copy_to_device(z, value) - CALL graph%pre_run() - CALL graph%run() - CALL graph%wait() + CALL graph%pre_run + CALL graph%run + CALL graph%wait CALL graph%print(0_C_LONG, (/ graph_ptr(z), graph_ptr(y) /)) CALL graph%copy_to_host(y, value) diff --git a/graph_tests/jit_test.cpp b/graph_tests/jit_test.cpp index 1f2eb2e963b9faaa5abde1ec4bbb61028270f2a1..5d878225af3ffc59bb750b6d505e3948a0508d93 100644 --- a/graph_tests/jit_test.cpp +++ b/graph_tests/jit_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file jit\_test.cpp +/// @file jit_test.cpp /// @brief Tests for the jit code. //------------------------------------------------------------------------------ @@ -329,7 +329,8 @@ template void run_math_tests() { /// /// @tparam DISPERSION_FUNCTION Class of dispersion function to use. /// -/// @param[in] eq Equilibrium for the dispersion function. +/// @param[in,out] eq Equilibrium for the dispersion function. +/// @param[in] tolarance The test tolarance for check results to. //------------------------------------------------------------------------------ template void run_dispersion_test(equilibrium::shared &eq, diff --git a/graph_tests/math_test.cpp b/graph_tests/math_test.cpp index c92272f7e69b65b0962bd1959dcdf0cec0cad794..670423d00ce71579baff044071031bfbdf7f3be0 100644 --- a/graph_tests/math_test.cpp +++ b/graph_tests/math_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file math\_test.cpp +/// @file math_test.cpp /// @brief Tests for math nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/node_test.cpp b/graph_tests/node_test.cpp index 1d1470ab8ff2e64fa3d43edac80314faafb28272..0a11aa9b0e48242cfdf56af5b524d5db8fda934c 100644 --- a/graph_tests/node_test.cpp +++ b/graph_tests/node_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file node\_test.cpp +/// @file node_test.cpp /// @brief Tests for the node interface. //------------------------------------------------------------------------------ diff --git a/graph_tests/physics_test.cpp b/graph_tests/physics_test.cpp index f8b6d550054c5518eac91090ab290a933f4a9184..3c6fe14c666fa1ba61ebd8ff7ede54c5b4abccce 100644 --- a/graph_tests/physics_test.cpp +++ b/graph_tests/physics_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file physics\_test.cpp +/// @file physics_test.cpp /// @brief Tests for math nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/piecewise_test.cpp b/graph_tests/piecewise_test.cpp index d213a7f3b56ca57a150708a87eee35feacc38a91..a07e7aee548d81c0a7f87952a1bcf4ec4021ca26 100644 --- a/graph_tests/piecewise_test.cpp +++ b/graph_tests/piecewise_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file piecewise\_test.cpp +/// @file piecewise_test.cpp /// @brief Tests for piecewise constants nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/random_test.cpp b/graph_tests/random_test.cpp index 346bc7bed913f18bf8e297f12ee4c186a703c546..e8ce1e8b0fdbb8df02d15289459343e89b1912b1 100644 --- a/graph_tests/random_test.cpp +++ b/graph_tests/random_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file random\_test.cpp +/// @file random_test.cpp /// @brief Tests for random nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/solver_test.cpp b/graph_tests/solver_test.cpp index 9da2e4e86bb0e8cdd5665f9b00ddd2f1db77d572..34528a5d47bc0d64157cebf61057db1564c6865f 100644 --- a/graph_tests/solver_test.cpp +++ b/graph_tests/solver_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file solver\_test.cpp +/// @file solver_test.cpp /// @brief Tests for solvers. //------------------------------------------------------------------------------ @@ -42,15 +42,15 @@ void test_solver(const typename SOLVER::base tolarance, auto dt_const = graph::constant(static_cast (dt)); SOLVER solve(w, kx, ky, kz, x, y, z, t, dt_const, eq); - const timeing::measure_diagnostic solver("init"); + const timing::measure_diagnostic solver("init"); auto residule = solve.init(kx, tolarance); solver.print(); - const timeing::measure_diagnostic compile("compile"); + const timing::measure_diagnostic compile("compile"); solve.compile(); compile.print(); - const timeing::measure_diagnostic step("step"); + const timing::measure_diagnostic step("step"); for (size_t i = 0; i < 5; i++) { solve.step(); assert(std::abs(solve.check_residule(0)) < std::abs(tolarance) && diff --git a/graph_tests/trigonometry_test.cpp b/graph_tests/trigonometry_test.cpp index ca4d349d9746cac11a030c5199bc2e3c8eb38106..40ba93b518b06ac134bdc132060479b3b3abb260 100644 --- a/graph_tests/trigonometry_test.cpp +++ b/graph_tests/trigonometry_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file trigonometry\_test.cpp +/// @file trigonometry_test.cpp /// @brief Tests for trig nodes. //------------------------------------------------------------------------------ diff --git a/graph_tests/vector_test.cpp b/graph_tests/vector_test.cpp index f116d769f2e666a9894383343b8739743e1b9d2f..184a28d2c5ff51bf13cc47fc8a649327b7726e2a 100644 --- a/graph_tests/vector_test.cpp +++ b/graph_tests/vector_test.cpp @@ -1,5 +1,5 @@ //------------------------------------------------------------------------------ -/// @file vector\_test.cpp +/// @file vector_test.cpp /// @brief Tests for the vector interface. //------------------------------------------------------------------------------ diff --git a/utilities/bin.py b/utilities/bin.py index b0b044045ff3ae79a1b9bb907370211374160f93..e339560bdb3f93bbc39dccf01407a73d11e9a0c7 100644 --- a/utilities/bin.py +++ b/utilities/bin.py @@ -1,6 +1,6 @@ #------------------------------------------------------------------------------- -## @file fix_NaN.py -## @brief Post processes result files. +## @file bin.py +## Post processes result files. #------------------------------------------------------------------------------- import netCDF4 @@ -13,7 +13,7 @@ import tensorflow ## Removes NaN's and noise spikes in the results. Also computes the power ## absorption and bins the power into a 2D grid. ## -## @param params[in] args Command line arguments. +## @param[in] args Command line arguments. #------------------------------------------------------------------------------- def main(**args): with netCDF4.Dataset('{}/bins.nc'.format(args['directory']), 'w') as bin_ref: diff --git a/utilities/fix_NaN.py b/utilities/fix_NaN.py index 01bd4b67c688e1fc8d2ab03a80f47f25a01e5cc0..8206d8624c7ec899c15959bc4adf8b0ee8344c05 100644 --- a/utilities/fix_NaN.py +++ b/utilities/fix_NaN.py @@ -1,6 +1,6 @@ #------------------------------------------------------------------------------- ## @file fix_NaN.py -## @brief Post processes result files. +## Post processes result files to remove NaN values. #------------------------------------------------------------------------------- import netCDF4 @@ -13,7 +13,7 @@ import numpy ## Removes NaN's and noise spikes in the results. Also computes the power ## absorption and bins the power into a 2D grid. ## -## @param params[in] args Command line arguments. +## @param[in] args Command line arguments. #------------------------------------------------------------------------------- def main(**args): with netCDF4.Dataset('{}/bins.nc'.format(args['directory']), 'w') as bin_ref: @@ -68,6 +68,7 @@ def main(**args): ## * --max_z Maximum vertical bin. #------------------------------------------------------------------------------- if __name__ == '__main__': +## Argument parser object for command line arguments. command_line_parser = argparse.ArgumentParser() command_line_parser.add_argument('-d', @@ -134,6 +135,7 @@ if __name__ == '__main__': type=float, metavar='MAX_R') +## The parsed command line arguments. args = vars(command_line_parser.parse_args()) # Remove empty arguments diff --git a/utilities/get_includes.py b/utilities/get_includes.py index 25877ca5c43f5122d144b8458e18f877124f7248..993183d4e7675ffd1d15cb5a2742210205e9acf8 100644 --- a/utilities/get_includes.py +++ b/utilities/get_includes.py @@ -1,6 +1,6 @@ #------------------------------------------------------------------------------- ## @file get_includes.py -## @brief Post processes result files. +## Get the needed include flags from the system compiler. #------------------------------------------------------------------------------- import argparse import subprocess @@ -8,7 +8,7 @@ import subprocess #------------------------------------------------------------------------------- ## @brief Parse the output to get the include directories. ## -## @param params[in] args Command line arguments. +## @param[in] args Command line arguments. #------------------------------------------------------------------------------- def main(**args): output = subprocess.run([args['compiler'], '-Wp,-v', '-x', 'c++', '/dev/null', '-fsyntax-only'], @@ -41,6 +41,7 @@ def main(**args): ## * --compiler Compiler command. #------------------------------------------------------------------------------- if __name__ == '__main__': +## Argument parser object for command line arguments. command_line_parser = argparse.ArgumentParser() command_line_parser.add_argument('-c', @@ -51,6 +52,7 @@ if __name__ == '__main__': help='Compiler command.', metavar='COMPILER') +## The parsed command line arguments. args = vars(command_line_parser.parse_args()) # Remove empty arguments