Structure of package_info.yaml

Overview

The package_info.yaml file contains the configuration used to generate PyChaste wrappers. The cppwg tool (which generates the wrappers) inspects the contents of package_info.yaml and uses this information to determine which C++ files to parse, which template parameter values to apply for explicit instantiation, and various other options that influence how the wrapper code is generated.

This page describes the structure of the package_info.yaml configuration file. A list of keys at each level is provided and an explanation is given for how the generated wrapper code is affected by the values set for each key.

For guidance on creating PyChaste wrappers from the configuration file, see the documentation on generating bindings.

Top-level keys

The top-level keys in package_info.yaml are:

• name
• source_includes
• smart_ptr_type
• common_include_file
• template_substitutions
• pointer_call_policy
• reference_call_policy
• modules

name

Project name. Used as a prefix for Python-importable modules.

Example:

name: chaste_project_PyChaste

This will result in module names such as _chaste_project_PyChaste_cell_based for the cell_based module.

source_includes

List of headers to be included in all C++ wrappers.

Example:

source_includes:
  - <set>
  - <vector>
  - <string>
  - <map>
  - SmartPointers.hpp
  - UblasIncludes.hpp

From the configuration above, the following will be added at the top of all wrapper code:

#include <set>
#include <vector>
#include <string>
#include <map>
#include "SmartPointers.hpp"
#include "UblasIncludes.hpp"

smart_ptr_type

Default smart pointer type to be used with PYBIND11_DECLARE_HOLDER_TYPE in all C++ wrappers:

Example:

smart_ptr_type: boost::shared_ptr

From the setting above, this will be be added in all wrapper code:

PYBIND11_DECLARE_HOLDER_TYPE(T, boost::shared_ptr<T>);

common_include_file

As part of the wrapper generation process, a wrapper_header_collection.hpp file is created which contains headers, template instantiations, and typedefs needed for all wrappers. For example:

#include "ChastePoint.hpp"
#include "Node.hpp"

template class ChastePoint<2>;
template class ChastePoint<3>;
template class Node<2>;
template class Node<3>;

typedef ChastePoint<2> ChastePoint2;
typedef ChastePoint<3> ChastePoint3;
typedef Node<2> Node2;
typedef Node<3> Node3;

The common_include_file key allows supplying the path to a manually created wrapper_header_collection.hpp. Setting it to OFF will cause the file to be generated automatically:

common_include_file: OFF

template_substitutions

This specifies a list of signature and replacement pairs for explicitly instantiating all matching templates.

Example:

template_substitutions:
  - signature: <unsigned ELEMENT_DIM, unsigned SPACE_DIM>
    replacement: [[2, 2], [3, 3]]
  - signature: <unsigned DIM, unsigned DIM>
    replacement: [[2, 2], [3, 3]]
  - signature: <unsigned ELEMENT_DIM, unsigned SPACE_DIM=ELEMENT_DIM>
    replacement: [[2, 2], [3, 3]]
  - signature: <unsigned SPACE_DIM>
    replacement: [[2], [3]]
  - signature: <unsigned DIM>
    replacement: [[2], [3]]

From the above settings, all templates which have the signature <unsigned ELEMENT_DIM, unsigned SPACE_DIM> will be explicitly instantiated in wrapper code with <2,2> and <3,3>, etc.

pointer_call_policy

The default value of pybind11::return_value_policy for pointers.

Example:

pointer_call_policy: reference

reference_call_policy

The default value of pybind11::return_value_policy for references.

Example:

reference_call_policy: reference_internal

modules

A list of Python modules to group the wrappers into.

Sections under modules

• name
• source_locations
• classes

Example:

modules:
- name: core
  source_locations: ...
  classes: ...
- name: cell_based
  source_locations: ...
  classes: ...

modules/name

The name of the module.

Example:

modules:
- name: core

modules/source_locations

Paths to source files to be included in the module

Example:

modules:
- name: core
  source_locations:
  - global/src
  - io/src
  - linalg/src

modules/classes

A list of classes to be wrapped into the module

Example:

modules:
- name: core
  classes:
  - name: Identifiable
  - name: PetscTools
  - name: ReplicatableVector
  - name: Timer
  - name: RelativeTo # enum
  - name: FileFinder
  - name: OutputFileHandler
  - name: ProgressReporter
  - name: RandomNumberGenerator
  - name: TimeStepper
  - name: ChasteBuildInfo

Sections under modules/classes

• name
• name_override
• constructor_arg_type_excludes
• custom_generator
• excluded_methods
• excluded_variables
• prefix_code
• source_file
• source_includes
• template_substitutions

modules/classes/name

The name of the class to wrap.

Example:

modules:
- name: mesh
  classes:
  - name: VertexMesh

modules/classes/name_override

A class name to be used in place of the original.

Example:

modules:
- name: mesh
  classes:
  - name: SharedPottsMeshGenerator
    name_override: PottsMeshGenerator

The configuration above results in wrapper code such as:

typedef SharedPottsMeshGenerator<2> PottsMeshGenerator2;

pybind11::class_<PottsMeshGenerator2, ...>(m, "PottsMeshGenerator2").def(...);

modules/classes/constructor_arg_type_excludes

List of constructor signatures to exclude from the wrapped class.

Example:

modules:
- name: mesh
  classes:
  - name: VertexMesh
    constructor_arg_type_excludes: 
    - TetrahedralMesh<3, 3>
    - TetrahedralMesh<2, 2>

modules/classes/custom_generator

Specifies the path to a custom script for generating wrappers for a class.

Example:

modules:
- name: cell_based
  classes:
  - name: CellsGenerator
    custom_generator: CPPWG_SOURCEROOT/projects/PyChaste/dynamic/wrapper_generators/CellsGenerator_custom.py

CPPWG_SOURCEROOT is a variable holding the path to the root directory of the source tree.

modules/classes/excluded_methods

Class methods that should not be wrapped.

Example:

modules:
- name: core
  classes:
  - name: PetscTools
    excluded_methods: 
    - GetWorld # MPI not wrapped here
    - Destroy # No non-const ref to PETSc types
    - ReadPetscObject
    - SetupMat

modules/classes/excluded_variables

Class variables that should not be wrapped. This setting currently does nothing as class variables are not wrapped.

Example:

modules:
- name: core
  classes:
  - name: PetscTools
    excluded_variables: 
    - MASTER_RANK # MPI not wrapped here

modules/classes/prefix_code

Custom C++ code to place at the top of a class wrapper.

Example:

modules:
- name: core
  classes:
  - name: PetscTools
    prefix_code:
    - PYBIND11_MAKE_OPAQUE(Vec); 
    - PYBIND11_MAKE_OPAQUE(Mat); 

modules/classes/source_file

Specifies the source file that contains the class definition. This is necessary if the filename does not match the class name.

Example:

modules:
- name: core
  classes:
  - name: ChasteBuildInfo
    source_file: Version.hpp

modules/classes/source_includes

A list of headers to be included in the C++ wrappers for this class.

Example:

modules:
- name: core
  classes:
  - name: PetscTools
    source_includes:
    - <petsc/private/vecimpl.h> # forward decl
    - <petsc/private/matimpl.h> # forward decl

modules/classes/template_substitutions

A list of explicit template instantiations to be made for this class.

Example:

modules:
- name: cell_based
  classes:
  - name: CellsGenerator
    template_substitutions:
      - signature: <class CELL_CYCLE_MODEL, unsigned DIM>
        replacement: 
        - [NoCellCycleModel, 2]
        - [NoCellCycleModel, 3]
        - [UniformCellCycleModel, 2]
        - [UniformCellCycleModel, 3]
        - [SimpleOxygenBasedCellCycleModel, 2]
        - [SimpleOxygenBasedCellCycleModel, 3]
        - [UniformG1GenerationalCellCycleModel, 2]
        - [UniformG1GenerationalCellCycleModel, 3]
        - [BiasedBernoulliTrialCellCycleModel, 2]
        - [BiasedBernoulliTrialCellCycleModel, 3]
        - [LabelDependentBernoulliTrialCellCycleModel, 2]
        - [LabelDependentBernoulliTrialCellCycleModel, 3]

The above configuration will instantiate templates such as CellsGenerator<NoCellCycleModel,2> etc.