# codegen package

Package providing the code generation framework.

Exported members: `CythonCodeObject`, `NumpyCodeObject`

## `_prefs` module

Module declaring general code generation preferences.

### Preferences

Code generation preferences

`codegen.loop_invariant_optimisations` = `True`

> Whether to pull out scalar expressions out of the statements, so that they are only evaluated once instead of once for every neuron/synapse/… Can be switched off, e.g. because it complicates the code (and the same optimisation is already performed by the compiler) or because the code generation target does not deal well with it. Defaults to `True`.

`codegen.max_cache_dir_size` = `1000`

> The size of a directory (in MB) with cached code for Cython that triggers a warning. Set to 0 to never get a warning.

`codegen.string_expression_target` = `'numpy'`

> Default target for the evaluation of string expressions (e.g. when indexing state variables). Should normally not be changed from the default numpy target, because the overhead of compiling code is not worth the speed gain for simple expressions.

> Accepts the same arguments as codegen.target, except for `'auto'`

`codegen.target` = `'auto'`

> Default target for code generation.

> Can be a string, in which case it should be one of:

> - `'auto'` the default, automatically chose the best code generation target available.

> - `'cython'`, uses the Cython package to generate C++ code. Needs a working installation of Cython and a C++ compiler.

> - `'numpy'` works on all platforms and doesn’t need a C compiler but is often less efficient.

> Or it can be a `CodeObject` class.

## `codeobject` module

Module providing the base `CodeObject` and related functions.

Exported members: `CodeObject`, `constant_or_scalar`

Classes

`CodeObject`(*args, **kw) | Executable code object.

Functions

`check_compiler_kwds`(compiler_kwds, ...) | Internal function to check the provided compiler keywords against the list of understood keywords.

`constant_or_scalar`(varname, variable) | Convenience function to generate code to access the value of a variable.

`create_runner_codeobj`(group, code, ...[, ...]) | Create a `CodeObject` for the execution of code in the context of a `Group`.

## `cpp_prefs` module

Preferences related to C++ compilation

### Preferences

C++ compilation preferences

`codegen.cpp.compiler` = `''`

> Compiler to use (uses default if empty). Should be `'unix'` or `'msvc'`.

> To specify a specific compiler binary on unix systems, set the `CXX` environment variable instead.

`codegen.cpp.define_macros` = `[]`

> List of macros to define; each macro is defined using a 2-tuple, where ‘value’ is either the string to define it to or None to define it without a particular value (equivalent of “#define FOO” in source or -DFOO on Unix C compiler command line).

`codegen.cpp.extra_compile_args` = `None`

> Extra arguments to pass to compiler (if None, use either `extra_compile_args_gcc` or `extra_compile_args_msvc`).

`codegen.cpp.extra_compile_args_gcc` = `['-w', '-O3', '-ffast-math', '-fno-finite-math-only', '-march=native', '-std=c++11']`

> Extra compile arguments to pass to GCC compiler

`codegen.cpp.extra_compile_args_msvc` = `['/Ox', '/w', '', '/MP']`

> Extra compile arguments to pass to MSVC compiler (the default `/arch:` flag is determined based on the processor architecture)

`codegen.cpp.extra_link_args` = `[]`

> Any extra platform- and compiler-specific information to use when linking object files together.

`codegen.cpp.headers` = `[]`

> A list of strings specifying header files to use when compiling the code. The list might look like [“<vector>”,“‘my_header’”]. Note that the header strings need to be in a form than can be pasted at the end of a #include statement in the C++ code.

`codegen.cpp.include_dirs` = `['/usr/include']`

> Include directories to use. The default value is `$prefix/include` (or `$prefix/Library/include` on Windows), where `$prefix` is Python’s site-specific directory prefix as returned by `sys.prefix`. This will make compilation use library files installed into a conda environment.

`codegen.cpp.libraries` = `[]`

> List of library names (not filenames or paths) to link against.

`codegen.cpp.library_dirs` = `['/usr/lib']`

> List of directories to search for C/C++ libraries at link time. The default value is `$prefix/lib` (or `$prefix/Library/lib` on Windows), where `$prefix` is Python’s site-specific directory prefix as returned by `sys.prefix`. This will make compilation use library files installed into a conda environment.

`codegen.cpp.msvc_architecture` = `''`

> MSVC architecture name (or use system architectue by default).

> Could take values such as x86, amd64, etc.

`codegen.cpp.msvc_vars_location` = `''`

> Location of the MSVC command line tool (or search for best by default).

`codegen.cpp.runtime_library_dirs` = `['/usr/lib']`

> List of directories to search for C/C++ libraries at run time. The default value is `$prefix/lib` (not used on Windows), where `$prefix` is Python’s site-specific directory prefix as returned by `sys.prefix`. This will make compilation use library files installed into a conda environment.

Exported members: `C99Check`, `compiler_supports_c99`, `get_compiler_and_args`, `get_msvc_env`

Classes

`C99Check`(name) | Helper class to create objects that can be passed as an `availability_check` to a `FunctionImplementation`.

Functions

`compiler_supports_c99`() |

`get_compiler_and_args`() | Returns the computed compiler and compilation flags

`get_msvc_env`() |

`has_flag`(compiler, flagname) |

## `get_cpu_flags` module

This script is used to ask for the CPU flags on Windows. We use this instead of importing the cpuinfo package, because recent versions of py-cpuinfo use the multiprocessing module, and any import of cpuinfo that is not within a `if __name__ == '__main__':` block will lead to the script being executed twice.

The CPU flags are printed to stdout encoded as JSON.

## `optimisation` module

Simplify and optimise sequences of statements by rewriting and pulling out loop invariants.

Exported members: `ArithmeticSimplifier`, `Simplifier`, `optimise_statements`

Classes

`ArithmeticSimplifier`(variables) | Carries out the following arithmetic simplifications:

`Simplifier`(variables, scalar_statements[, ...]) | Carry out arithmetic simplifications (see `ArithmeticSimplifier`) and loop invariants

Functions

`cancel_identical_terms`(primary, inverted) | Cancel terms in a collection, e.g. a+b-a should be cancelled to b.

`collect`(node) | Attempts to collect commutative operations into one and simplifies them.

`collect_commutative`(node, primary, inverted, ...) |

`evaluate_expr`(expr, ns) | Try to evaluate the expression in the given namespace

`expression_complexity`(expr, variables) |

`optimise_statements`(scalar_statements, ...) | Optimise a sequence of scalar and vector statements

`reduced_node`(terms, op) | Reduce a sequence of terms with the given operator

## `permutation_analysis` module

Module for analysing synaptic pre and post code for synapse order independence.

Exported members: `OrderDependenceError`, `check_for_order_independence`

Classes

`OrderDependenceError` |

Functions

`check_for_order_independence`(statements, ...) | Check that the sequence of statements doesn't depend on the order in which the indices are iterated through.

## `statements` module

Module providing the `Statement` class.

Classes

`Statement`(var, op, expr, comment, dtype[, ...]) | A single line mathematical statement.

## `targets` module

Module that stores all known code generation targets as `codegen_targets`.

Exported members: `codegen_targets`

## `templates` module

Handles loading templates from a directory.

Exported members: `Templater`

Classes

`CodeObjectTemplate`(template, template_source) | Single template object returned by `Templater` and used for final code generation

`LazyTemplateLoader`(environment, extension) | Helper object to load templates only when they are needed.

`MultiTemplate`(module) | Code generated by a `CodeObjectTemplate` with multiple blocks

`Templater`(package_name, extension[, ...]) | Class to load and return all the templates a `CodeObject` defines.

Functions

`autoindent`(code) |

`autoindent_postfilter`(code) |

`variables_to_array_names`(variables[, ...]) |

## `translation` module

This module translates a series of statements into a language-specific syntactically correct code block that can be inserted into a template.

It infers whether or not a variable can be declared as constant, etc. It should handle common subexpressions, and so forth.

The input information needed:

- The sequence of statements (a multiline string) in standard mathematical form

- The list of known variables, common subexpressions and functions, and for each variable whether or not it is a value or an array, and if an array what the dtype is.

- The dtype to use for newly created variables

- The language to translate to

Exported members: `analyse_identifiers`, `get_identifiers_recursively`

Classes

`LineInfo`(**kwds) | A helper class, just used to store attributes.

Functions

`analyse_identifiers`(code, variables[, recursive]) | Analyses a code string (sequence of statements) to find all identifiers by type.

`get_identifiers_recursively`(expressions, ...) | Gets all the identifiers in a list of expressions, recursing down into subexpressions.

`is_scalar_expression`(expr, variables) | Whether the given expression is scalar.

`make_statements`(code, variables, dtype[, ...]) | Turn a series of abstract code statements into Statement objects, inferring whether each line is a set/declare operation, whether the variables are constant or not, and handling the cacheing of subexpressions.

## Subpackages

- generators package
  - `GSL_generator` module
  - `base` module
  - `cpp_generator` module
  - `cython_generator` module
  - `numpy_generator` module
- runtime package
  - Subpackages