Symbol Quick Reference

This is a table for checking the meaning of symbols and keywords while you read MISO’s code in the C++ chapters (Chapters 2–6) and in Chapters 7–9. You do not need to read it through. From the “Details” column of each row, you can go back to the chapter in the main text.

Contents

Basics of reading: declaration or expression?
* and & and &&
Symbols that refer to names and members (:: . ->)
Brackets (angle, square, round, and curly)
Other operators
Preprocessor symbols (#)
Keywords
MISO and CUDA symbols
Order of checks when reading a declaration

Basics of reading: declaration or expression?

In C++, the same symbol means different things in a declaration (a statement that creates a new name) and in an expression (a computation that uses an existing name). When you are unsure about a symbol, first check whether the line is creating a name or using one.

double a = 1.0;
double *p = &a;  // * in a declaration: p is a "pointer to double". & in an expression: address of a
*p = 2.0;        // * in an expression: write 2.0 to what p points to (a)
double &r = a;   // & in a declaration: r is an alias (reference) of a

In the tables below, read a and b as double variables, p as a pointer of type double *, and T as a template argument type.

* and & and &&

Form you see	Declaration or expression	Meaning	Details
`double *p = &a;`	Declaration	`p` is a pointer to a `double`. Writing `double* p` means the same	Chapter 3
`p`、`p = 5.0;`	Expression	Reads and writes the value that `p` points to	Chapter 3
`a * b`	Expression	Multiplication	Chapter 2
`double &r = a;`	Declaration	`r` is another name (a reference) for `a`. Assigning to `r` changes `a`	Chapter 3
`void f(double &x)`	Declaration (parameter)	Pass by reference. If you change `x` inside the function, the caller’s variable changes	Chapter 3
`const Config &config`	Declaration (parameter)	Pass by reference for reading only. It does not copy and does not modify	Chapter 3
`&a`	Expression	Takes the address of `a`	Chapter 3
`&T::gm`	Expression	An expression that points to member `gm` of class `T`. MISO uses it to check “whether `gm` exists”	Chapter 6
`x && y`	Expression	Logical AND (and). It is Fortran’s `.and.`	Chapter 2
`Array3D(Array3D &&other)`	Declaration (parameter)	An rvalue reference. It is used to receive a move (a transfer of contents)	Chapter 4
`const double *p`	Declaration	Forbids modification through `*p`. You can switch what `p` points to	Chapter 3
`double *const p`	Declaration	Forbids switching what `p` points to. You can modify through `*p`	Chapter 3
`T *data_`	Declaration (member)	A pointer to the start of the array, held by `Array3DView` and others	Chapter 4
`char **argv`	Declaration (parameter)	A pointer to a pointer. You see it in the command-line arguments of `main`	Chapter 3

MISO’s source attaches * and & to the name, as in double *p (the .clang-format setting). double* p and double *p mean the same thing.

Symbols that refer to names and members (:: . ->)

Form you see	Meaning	Details
`std::cout`、`miso::mhd::MHD`	A name inside a namespace. `miso::mhd::` means “inside `mhd` inside `miso`”	Chapter 2
`backend::Host`	A type inside the namespace `miso::backend`. After `using namespace miso;` you can omit `miso::`	Chapter 2, Chapter 6
`::sinf(x)`	A leading `::` refers to a name outside the namespaces (the outermost one)	Chapter 2
`Shape::ndims`、`std::true_type::value`	A name belonging to a class (a `static` member). You can use it without creating an object	Chapter 4, Chapter 6
`T::gm`	A member of the template argument `T`	Chapter 6
`grid.i_total`、`qq.ro(i, j, k)`	Uses a member of an object (or reference)	Chapter 4
`p->x`	Uses a member of what the pointer `p` points to. It is the same as `(*p).x`	Chapter 4
`this->config`	Inside a member function, uses a member through `this`, the pointer to itself. Usually you omit `this->`	Chapter 4

Brackets (<> [] () {})

Form you see	Meaning	Details
`#include <vector>`	Includes a header in a fixed location, such as the standard library	Chapter 1, Chapter 2
`#include "array3d.hpp"`	Looks for a header relative to the location of your own file and includes it	Chapter 2
`a < b`、`n << 1`、`std::cout << x`	Comparison, bit shift, and output	Chapter 2
`std::vector<double>`、`Array3D<Real, Backend>`	Template arguments. The angle brackets are part of the type name, forming a single name	Chapter 6
`template <typename Real>`	Declares the name of a type to be decided later	Chapter 6
`template <>`	A full specialization (a definition in which all template arguments are fixed)	Chapter 6
`pi<Real>`、`mpi::data_type<Real>()`	Uses a variable template or function template by specifying a type	Chapter 6
`static_cast<Real>(x)`	Converts `x` to type `Real`	Chapter 2
`kernel<<<grid, block>>>(...)`	A launch of a CUDA kernel. It is not a C++ symbol	Chapter 9
`x[i]`、`grid.x[i]`	An element of an array or `std::vector`. Indexing is zero-based	Chapter 2, Chapter 7
`double x[3];`、`int shape_[3]`	`[]` in a declaration creates an array with a fixed number of elements	Chapter 3
`new T[n]`、`delete[] data_`	Allocating and freeing an array	Chapter 3, Chapter 4
`T &operator[](int idx)`	The definition of an operator that lets you write `a[idx]`	Chapter 4
`[=]`、`[&]`、`MISO_LAMBDA(int i) { ... }`	The start of a lambda expression (an unnamed function). `[=]` captures outside variables by value copy, and `[&]` by reference	Chapter 7
`f(x)`、`square<double>(1.5)`	A function call	Chapter 2
`double f(double x);`	`()` in a declaration is the list of parameters	Chapter 2
`qq.ro(i, j, k)`	Reading and writing an array element through `operator()`. A notation modeled on Fortran’s `ro(i, j, k)`	Chapter 4
`T &operator()(int i0, int i1, int i2)`	The definition of an operator that lets you write `a(i, j, k)`	Chapter 4
`Array3D<Real> pr(nx, ny, nz);`	`()` after a declaration holds the values passed to the constructor	Chapter 4
`(a + b) * c`	Parentheses that determine the order of computation	Chapter 2
`if (...) { ... }`、`for (...) { ... }`	A group of statements (a block). A variable declared inside ends its lifetime at `}`	Chapter 2, Chapter 3
`struct Host {};`	The body of a class. `{}` means the contents are empty	Chapter 4, Chapter 6
`int n{3};`、`Range1D range{0, n};`	Initialization with braces	Chapter 2, Chapter 4
`backend::Host{}`、`Backend{}`	An expression that creates a value of a type without an initial value. Used to pass a tag type to a function	Chapter 6
`: grid(grid), qq(grid)`	The member initializer list of a constructor (written between `)` and `{`)	Chapter 4

The distinction between <...> and (...) is important. In Array3D<float> a(4, 4, 4);, float specifies a type, and 4, 4, 4 are the values passed to the constructor.

Other operators

Form you see	Meaning	Details
`a = b`	Assignment. Comparison is `==`	Chapter 2
`a == b`、`a != b`	Equal and not equal (Fortran’s `==` and `/=`)	Chapter 2
`x \|\| y`、`!x`	Logical OR (or) and negation (Fortran’s `.or.` and `.not.`)	Chapter 2
`i % n`	The remainder of integer division (Fortran’s `mod(i, n)`)	Chapter 2
`++i`、`i++`	Increases `i` by 1	Chapter 2
`a += b`	The same as `a = a + b`. There are also `-=`, `*=`, and `/=`	Chapter 2
`c ? a : b`	`a` if `c` is true, `b` if false	Chapter 2
`~Array3D()`	The name of the destructor (a cleanup function)	Chapter 4
`= default`、`= delete`	A specifier written in place of a function body. It makes the compiler provide the function or makes it unusable	Chapter 4
`: public ModelBase<...>`	`:` in a class declaration is inheritance	Chapter 5

Preprocessor symbols (#)

Lines that start with # are processed by the preprocessor before compilation. This is text replacement, separate from C++ grammar.

Form you see	Meaning	Details
`#include`	Includes the contents of a file at that place	Chapter 1, Chapter 2
`#pragma once`	Prevents the same header from being included twice	Chapter 2
`#define NAME value`	Defines a macro that replaces `NAME` with the text that follows	Chapter 2
`#ifdef USE_CUDA` 〜 `#else` 〜 `#endif`	Selects the part to compile depending on whether a macro is defined. It is the same as Fortran’s `#ifdef`	Chapter 2
`#ifdef __CUDACC__`	A part that is active only when building with the CUDA compiler (nvcc)	Chapter 6, Chapter 9
`#undef NAME`	Cancels the definition of a macro	Chapter 6
`\` at the end of a line	Continues the macro definition onto the next line	Chapter 6
`##` in a macro	Joins the parts before and after into a single name (`has_##name` → `has_vx`)	Chapter 6
`#name` in a macro	Turns the argument into a string (`#name` → `"vx"`)	Chapter 6

Keywords

This collects mainly those whose meaning changes depending on their position in a declaration.

Keywords	Form you see and its meaning	Details
`const`	`const Real gm_ = gm;`: a variable whose value cannot be changed	Chapter 2
	`const T &x`: a reference for reading only	Chapter 3
	`const T p` and `T const p`: to the left of the `*` it fixes what is pointed to; to the right it fixes the pointer itself	Chapter 3
	`int size() const`: a member function that does not change member variables	Chapter 4
	`Array3DView<const Real>`: a view that only reads the elements	Chapter 4
`constexpr`	`constexpr int n_fields = 9;`: a constant whose value is determined at compile time	Chapter 2
`auto`	`auto dt = mhd.cfl(d.eos);`: determines the type from the initial value. `auto &d = derived();` becomes a reference	Chapter 2, Chapter 3
`using`	`using Real = float;`: a type alias	Chapter 2
	`using namespace miso;`: lets you use names in the namespace without `miso::`	Chapter 2
	`using Source = decltype(d.src);`: gives an alias to a deduced type inside a template	Chapter 6
`template`	`template <typename T> ...`: a template declaration	Chapter 6
	`template <> ...`: a full specialization	Chapter 6
	`x.template as<bool>()`: a marker showing that the name that follows is a template	Chapter 6
`typename`	`template <typename T>`: shows that `T` is the name of a type. Writing `class` means the same	Chapter 6
	`typename T::value_type`: shows that a name belonging to a template argument is a type	Chapter 6
`inline`	Attached to ordinary functions and variables whose definitions are placed in a header. It is not a specifier for making things faster	Chapter 2, Chapter 6
`static`	Inside a class, a member that belongs to the class regardless of any object	Chapter 4
`explicit`	Forbids implicit type conversion by a constructor	Chapter 4
`noexcept`	Indicates that the function does not let exceptions escape	Chapter 4
`virtual`	A virtual function whose derived-class version is chosen at run time. MISO does not use it	Chapter 5
`decltype(expression)`	Determines the type of an expression without evaluating it	Chapter 6
`if constexpr`	A branch whose condition is determined at compile time. The side not selected is not included	Chapter 6
`static_assert`	Makes it a compile error if the condition is false	Chapter 6
`nullptr`	A pointer that points nowhere	Chapter 3
`this`	Inside a member function, a pointer to itself. Using it inside a lambda causes problems on the GPU	Chapter 4, Chapter 7, Chapter 9
`struct`、`class`	A class declaration. `struct` is `public` by default, and `class` is `private` by default	Chapter 4

MISO and CUDA symbols

These are not C++ keywords, but names provided by MISO and CUDA.

Form you see	Meaning	Details
`Real`	The floating-point type that the demos fix with `using Real = float;`. On the library side it is a template argument	Chapter 2, Chapter 6
`Backend`、`backend::Host`、`backend::CUDA`	Tag types that represent the place of computation and memory (`miso/include/miso/backend.hpp`)	Chapter 6
`MISO_LAMBDA`	A macro that marks the start of a lambda expression. In a CPU build it is `[=]`, and in a CUDA build it is `[=] __host__ __device__` (`miso/include/miso/execution.hpp`)	Chapter 7, Chapter 9
`__host__`、`__device__`	A specifier for whether a function can be called from the CPU or the GPU. It is empty in a CPU-only build (`miso/include/miso/cuda_compat.hpp`)	Chapter 9
`__global__`	A specifier for a kernel function that runs on the GPU	Chapter 9
`MPI_Comm`, `MPI_Allreduce`, and so on	Types and functions of the MPI library	Chapter 8

Order of checks when reading a declaration

Read a long declaration by splitting it up in the following order.

Find the name. Check whether it declares a variable, a function, or a type.
Read the type. The type includes everything up to <...>. If template <...> comes before, the names inside the angle brackets are types decided later.
Distinguish value, reference, and pointer. Look at whether & or * is attached to the name.
Check what const applies to. Distinguish whether it is the value, what is pointed to, the pointer itself, or the member function.
Check how it is created and its lifetime. Trace which objects the initial value, parameters, and return value use, and how long they remain usable.

As an example, let us read a declaration from miso/include/miso/mhd_integrator.hpp in parts.

template <typename Real, typename Source>
__host__ __device__ inline Real source_vx(const Source &src,
                                          const FieldsView<const Real> &qq,
                                          int i, int j, int k);

Part	How to read it
`template <typename Real, typename Source>`	`Real` and `Source` are types decided later
`__host__ __device__`	A function that can be called from both the CPU and the GPU
`inline`	A function placed in a header
`Real source_vx(...)`	The name is `source_vx` and the return type is `Real`
`const Source &src`	Receives the source-term object as a reference for reading only
`const FieldsView<const Real> &qq`	Receives a view that only reads the elements (`FieldsView<const Real>`) as a reference for reading only
`int i, int j, int k`	Receives the grid-point indices by value

For the details of the grammar, see the C++17 draft standard N4659: declaring references, the rules for const, and templates.