Python/Module.cpp File Reference

#include <FieldUtils/Module.h>
#include <LibUtilities/Python/NekPyConfig.hpp>
#include <boost/program_options.hpp>
#include <boost/python/raw_function.hpp>

Go to the source code of this file.

Classes
struct	ModuleWrap< MODTYPE >
	Module wrapper to handle virtual function calls in Module and its subclasses as defined by the template parameter. More...
struct	ModuleTypeProxy< MODTYPE >
struct	ModuleTypeProxy< InputModule >
struct	ModuleTypeProxy< ProcessModule >
struct	ModuleTypeProxy< OutputModule >
class	ModuleRegisterHelper
struct	ModuleWrapConverter< MODTYPE >
struct	PythonModuleClass< MODTYPE >

Functions
void	Module_Process (ModuleSharedPtr m)
template<typename T >
T	Module_GetConfig (std::shared_ptr< Module > mod, const std::string &key)
void	Module_GetVtkGrid (std::shared_ptr< Module > mod)
template<typename MODTYPE >
ModuleSharedPtr	Module_Create (py::tuple args, py::dict kwargs)
	Lightweight wrapper for Module factory creation function. More...
void	Module_RegisterConfig (std::shared_ptr< Module > mod, std::string const &key, std::string const &value)
	Lightweight wrapper for FieldUtils::Module::RegisterConfig. More...
template<typename MODTYPE >
void	ModuleWrap_AddConfigOption (std::shared_ptr< ModuleWrap< MODTYPE > > mod, std::string const &key, std::string const &defValue, std::string const &desc, bool isBool)
void	ModuleCapsuleDestructor (PyObject *ptr)
void	Module_Register (ModuleType const &modType, std::string const &modName, py::object &obj)
	Lightweight wrapper for the Module factory RegisterCreatorFunction, to support the ability for Python subclasses of Module to register themselves with the Nektar++ Module factory. More...
void	export_Module ()

Function Documentation

export_Module()

void export_Module

(

)

Definition at line 437 of file Python/Module.cpp.

{
    // Export ModuleType enum.
    NEKPY_WRAP_ENUM_STRING(ModuleType, ModuleTypeMap);
 
#ifdef NEKTAR_USING_VTK
    VTK_PYTHON_CONVERSION(vtkUnstructuredGrid);
#endif
 
    // Define ModuleWrap to be implicitly convertible to a Module, since it
    // seems that doesn't sometimes get picked up.
    py::implicitly_convertible<std::shared_ptr<ModuleWrap<Module>>,
                               std::shared_ptr<Module>>();
    py::implicitly_convertible<std::shared_ptr<ModuleWrap<InputModule>>,
                               std::shared_ptr<Module>>();
    py::implicitly_convertible<std::shared_ptr<ModuleWrap<OutputModule>>,
                               std::shared_ptr<Module>>();
    py::implicitly_convertible<std::shared_ptr<ModuleWrap<ProcessModule>>,
                               std::shared_ptr<Module>>();
 
    // Wrapper for the Module class. Note that since Module contains a pure
    // virtual function, we need the ModuleWrap helper class to handle this for
    // us. In the lightweight wrappers above, we therefore need to ensure we're
    // passing std::shared_ptr<Module> as the first argument, otherwise they
    // won't accept objects constructed from Python.
    py::class_<ModuleWrap<Module>, std::shared_ptr<ModuleWrap<Module>>,
               boost::noncopyable>("Module", py::init<FieldSharedPtr>())
 
        // Process function for this module.
        .def("Process", py::pure_virtual(&Module_Process))
        .def("Run", py::pure_virtual(&Module_Process))
 
        // Configuration options.
        .def("RegisterConfig", Module_RegisterConfig,
             (py::arg("key"), py::arg("value") = ""))
        .def("PrintConfig", &Module::PrintConfig)
        .def("SetDefaults", &Module::SetDefaults)
        .def("GetStringConfig", Module_GetConfig<std::string>)
        .def("GetFloatConfig", Module_GetConfig<double>)
        .def("GetIntConfig", Module_GetConfig<int>)
        .def("GetBoolConfig", Module_GetConfig<bool>)
        .def("AddConfigOption", ModuleWrap_AddConfigOption<Module>,
             (py::arg("key"), py::arg("defValue"), py::arg("desc"),
              py::arg("isBool") = false))
        .def("GetVtkGrid", Module_GetVtkGrid,
             py::return_value_policy<py::return_by_value>())
 
        // Allow direct access to field object through a property.
        .def_readwrite("field", &ModuleWrap<Module>::m_f)
 
        // Factory functions.
        .def("Register", &Module_Register)
        .staticmethod("Register");
 
    ModuleWrapConverter<Module>();
 
    PythonModuleClass<InputModule>("InputModule");
    PythonModuleClass<ProcessModule>("ProcessModule");
    PythonModuleClass<OutputModule>("OutputModule");
}

References Module_GetVtkGrid(), Module_Process(), Module_Register(), Module_RegisterConfig(), Nektar::FieldUtils::ModuleTypeMap, NEKPY_WRAP_ENUM_STRING, and VTK_PYTHON_CONVERSION.

Referenced by BOOST_PYTHON_MODULE().

Module_Create()

template<typename MODTYPE >

ModuleSharedPtr Module_Create	(	py::tuple	args,
		py::dict	kwargs
	)

Lightweight wrapper for Module factory creation function.

Parameters

modType	Module type (input/process/output).
modName	Module name (typically filename extension).
field	Field that will be passed between modules.

Template Parameters

MODTYPE

Subclass of Module (e.g #InputModule, #OutputModule)

Definition at line 193 of file Python/Module.cpp.

{
    ModuleType modType = ModuleTypeProxy<MODTYPE>::value;
 
    using NekError = ErrorUtil::NekError;
 
    if (modType == eProcessModule && py::len(args) != 2)
    {
        throw NekError("ProcessModule.Create() requires two arguments: "
                       "module name and a Field object.");
    }
    else if (modType != eProcessModule && py::len(args) < 2)
    {
        throw NekError(ModuleTypeMap[modType] +
                       "Module.Create() requires "
                       "two arguments: module name and a Field object; "
                       "optionally a filename.");
    }
 
    std::string modName = py::extract<std::string>(args[0]);
    ModuleKey modKey    = std::make_pair(modType, modName);
 
    if (!py::extract<FieldSharedPtr>(args[1]).check())
    {
        throw NekError("Second argument to Create() should be a Field object.");
    }
 
    FieldSharedPtr field = py::extract<FieldSharedPtr>(args[1]);
    ModuleSharedPtr mod  = GetModuleFactory().CreateInstance(modKey, field);
 
    if (modType == eInputModule)
    {
        // For input modules we can try to interpret the remaining arguments as
        // input files. Assume that the file's type is identical to the module
        // name.
        for (int i = 2; i < py::len(args); ++i)
        {
            std::string in_fname = py::extract<std::string>(args[i]);
            mod->RegisterConfig("infile", in_fname);
            mod->AddFile(modName, in_fname);
        }
    }
    else if (modType == eOutputModule && py::len(args) >= 3)
    {
        // For output modules we can try to interpret the remaining argument as
        // an output file.
        mod->RegisterConfig("outfile", py::extract<std::string>(args[2]));
    }
 
    // Process keyword arguments.
    py::list items = kwargs.items();
 
    for (int i = 0; i < py::len(items); ++i)
    {
        std::string arg = py::extract<std::string>(items[i][0]);
 
        if (arg == "infile" && modKey.first == eInputModule)
        {
            py::extract<py::dict> dict_check(items[i][1]);
 
            if (!dict_check.check())
            {
                throw NekError("infile should be a dictionary.");
            }
 
            py::dict ftype_fname_dict = py::extract<py::dict>(items[i][1]);
            py::list ft_fn_items      = ftype_fname_dict.items();
            for (int i = 0; i < py::len(ft_fn_items); ++i)
            {
                std::string f_type =
                    py::extract<std::string>(ft_fn_items[i][0]);
                std::string f_name = py::extract<std::string>(
                    ft_fn_items[i][1].attr("__str__")());
                mod->RegisterConfig(arg, f_name);
                mod->AddFile(f_type, f_name);
            }
        }
        else
        {
            std::string val =
                py::extract<std::string>(items[i][1].attr("__str__")());
            mod->RegisterConfig(arg, val);
        }
    }
 
    mod->SetDefaults();
 
    return mod;
}

References Nektar::LibUtilities::NekFactory< tKey, tBase, tParam >::CreateInstance(), Nektar::FieldUtils::eInputModule, Nektar::FieldUtils::eOutputModule, Nektar::FieldUtils::eProcessModule, FilterPython_Function::field, Nektar::FieldUtils::GetModuleFactory(), and Nektar::FieldUtils::ModuleTypeMap.

Module_GetConfig()

template<typename T >

T Module_GetConfig	(	std::shared_ptr< Module >	mod,
		const std::string &	key
	)

Definition at line 132 of file Python/Module.cpp.

{
    return mod->GetConfigOption(key).as<T>();
}

Module_GetVtkGrid()

void Module_GetVtkGrid

(

std::shared_ptr< Module >

mod

)

Definition at line 177 of file Python/Module.cpp.

{
    using NekError = ErrorUtil::NekError;
    throw NekError("Nektar++ has not been compiled with VTK support.");
}

Referenced by export_Module().

Module_Process()

void Module_Process

(

ModuleSharedPtr

m

)

Definition at line 106 of file Python/Module.cpp.

{
    if (m->m_f->m_nParts > 1)
    {
        if (m->GetModulePriority() == eOutput)
        {
            m->m_f->m_comm = m->m_f->m_partComm;
            if (m->GetModuleName() != "OutputInfo")
            {
                m->RegisterConfig("writemultiplefiles");
            }
        }
        else if (m->GetModulePriority() == eCreateGraph)
        {
            m->m_f->m_comm = m->m_f->m_partComm;
        }
        else
        {
            m->m_f->m_comm = m->m_f->m_defComm;
        }
    }
    m->SetDefaults();
    m->Process(m->m_f->m_vm);
}

References Nektar::FieldUtils::eCreateGraph, and Nektar::FieldUtils::eOutput.

Referenced by export_Module(), and PythonModuleClass< MODTYPE >::PythonModuleClass().

Module_Register()

void Module_Register	(	ModuleType const &	modType,
		std::string const &	modName,
		py::object &	obj
	)

Lightweight wrapper for the Module factory RegisterCreatorFunction, to support the ability for Python subclasses of Module to register themselves with the Nektar++ Module factory.

This function wraps the NekFactory RegisterCreatorFunction. This function expects a function pointer to a C++ object that will construct a Module. In this case we therefore need to construct a function call that will construct our Python object (which is a subclass of Module), and then pass this back to Boost.Python to give the Python object back.

We have to do some indirection here to get this to work, but we can achieve this with the following strategy:

• Create a ModuleRegisterHelper object, which as an argument will store the Python class instance that will be instantiated from the Python side.
• Using std::bind, construct a function pointer to the helper's creation function, ModuleRegisterHelper::create.
• Create a Python capsule that will contain the ModuleRegisterHelper instance, and register this in the global namespace of the current module. This then ties the capsule to the lifetime of the module.

Definition at line 365 of file Python/Module.cpp.

{
    // Create a module register helper, which will call the C++ function to
    // create the module.
    ModuleRegisterHelper *helper = new ModuleRegisterHelper(obj);
 
    // Register this with the module factory using std::bind to grab a function
    // pointer to that particular object's function.
    GetModuleFactory().RegisterCreatorFunction(
        ModuleKey(modType, modName), std::bind(&ModuleRegisterHelper::create,
                                               helper, std::placeholders::_1));
 
    // Create a capsule that will be embedded in the __main__ namespace. So
    // deallocation will occur, but only once Python ends or the Python module
    // is deallocated.
    std::string modkey =
        "_" + std::string(ModuleTypeMap[modType]) + "_" + modName;
 
#if PY_MAJOR_VERSION == 2
    py::object capsule(
        py::handle<>(PyCObject_FromVoidPtr(helper, ModuleCapsuleDestructor)));
#else
    py::object capsule(
        py::handle<>(PyCapsule_New(helper, nullptr, ModuleCapsuleDestructor)));
#endif
 
    // Embed this in __main__.
    py::import("__main__").attr(modkey.c_str()) = capsule;
}

References ModuleRegisterHelper::create(), Nektar::FieldUtils::GetModuleFactory(), ModuleCapsuleDestructor(), Nektar::FieldUtils::ModuleTypeMap, and Nektar::LibUtilities::NekFactory< tKey, tBase, tParam >::RegisterCreatorFunction().

Referenced by export_Module().

Module_RegisterConfig()

void Module_RegisterConfig	(	std::shared_ptr< Module >	mod,
		std::string const &	key,
		std::string const &	value
	)

Lightweight wrapper for FieldUtils::Module::RegisterConfig.

Parameters

mod	Module to call
key	Configuration key.
value	Optional value (some configuration options are boolean).

Definition at line 290 of file Python/Module.cpp.

{
    mod->RegisterConfig(key, value);
}

Referenced by export_Module().

ModuleCapsuleDestructor()

void ModuleCapsuleDestructor

(

PyObject *

ptr

)

Definition at line 335 of file Python/Module.cpp.

{
    ModuleRegisterHelper *tmp =
        (ModuleRegisterHelper *)PyCapsule_GetPointer(ptr, nullptr);
    delete tmp;
}

Referenced by Module_Register().

ModuleWrap_AddConfigOption()

template<typename MODTYPE >

void ModuleWrap_AddConfigOption	(	std::shared_ptr< ModuleWrap< MODTYPE > >	mod,
		std::string const &	key,
		std::string const &	defValue,
		std::string const &	desc,
		bool	isBool
	)

Definition at line 297 of file Python/Module.cpp.

{
    mod->AddConfigOption(key, defValue, desc, isBool);
}