element_python.h

// Copyright 2009-2025 NTESS. Under the terms
// of Contract DE-NA0003525 with NTESS, the U.S.
// Government retains certain rights in this software.
//
// Copyright (c) 2009-2025, NTESS
// All rights reserved.
//
// This file is part of the SST software package. For license
// information, see the LICENSE file in the top level directory of the
// distribution.

#ifndef SST_CORE_MODEL_ELEMENT_PYTHON_H
#define SST_CORE_MODEL_ELEMENT_PYTHON_H

#include "sst/core/eli/elementinfo.h"

#include <string>
#include <vector>

namespace SST {

using genPythonModuleFunction = void* (*)(void);

/** Class to represent the code that needs to be added to create the
 * python module struture for the library.
 */
class SSTElementPythonModuleCode
{

private:
    //! Pointer to parent module.
    /** Parent module.  This will be nullptr if this is the primary module (i.e. sst.*) */
    SSTElementPythonModuleCode* parent;

    //! Simple name of the module.
    /** Simple name of the module.  Full name will be parant_full_name.module_name */
    std::string module_name;

    //! Code to be compiled
    ///
    /// The code to be added under the specified module name.  Python
    /// files will need to be turned into a char array.  One way to do
    /// this is to use the following in your Makefile:
    /// %.inc: %.py
    ///         od -v -t x1 < $< | sed -e 's/^[^ ]*[ ]*//g' -e '/^\s*$$/d' -e 's/\([0-9a-f]*\)[ $$]*/0x\1,/g' > $@
    ///
    // (Used different comment style because command above would have ended a c-style comment block)
    char* code;

    //! Filename used when reporting errors
    /** Filename that will be used in any error messages generated
     * when loading the python module into the interpreter.
     */
    std::string filename;

    //! Private constructor.  Called by friend class SSTElementPythonModule.
    /**
     *  Private constructor.  Called by friend class SSTElementPythonModule.
     *  \param parent pointer to parent module
     *  \param module_name simple name of the module
     *  \param code code to be compiled
     *  \param filename filname used when reporting errors
     *  \sa parent, module_name, code, filename
     */
    SSTElementPythonModuleCode(
        SSTElementPythonModuleCode* parent, const std::string& module_name, char* code, std::string filename) :
        parent(parent),
        module_name(module_name),
        code(code),
        filename(filename)
    {
        // If no filename for debug is given, just set it to the full name of the module
        if ( filename == "" ) {
            filename = getFullModuleName();
        }
    }

    //! load the code as a module into the interpreter
    /**
     *  Load the code as a module into the interpreter.
     *  Both return type and pyobj are actually PyObject*, but passing
     *  as a void* to avoid including python header files in base SST
     *  header files.
     *  \param parent_module parent module (passed as PyObject*)to load this module under
     *  \return pointer (as PyObject*) to the created module
     */
    virtual void* load(void* parent_module);

    //! Vector of sub_modules
    std::vector<SSTElementPythonModuleCode*> sub_modules;

    friend class SSTElementPythonModule;

public:
    //! Add a submodule to the module
    ///
    /// Python files will need to be turned into a char array (code parameter).  One way to do
    /// this is to use the following in your Makefile:
    /// \verbatim %.inc: %.py
    ///         od -v -t x1 < $< | sed -e 's/^[^ ]*[ ]*//g' -e '/^\s*$$/d' -e 's/\([0-9a-f]*\)[ $$]*/0x\1,/g' > $@
    ///         \endverbatim
    /// \param module_name simple name of the module
    /// \param code code to be compiled
    /// \param filename filname used when reporting errors
    ///
    ///
    SSTElementPythonModuleCode* addSubModule(const std::string& module_name, char* code, const std::string& filename);

    //! Add an empty submodule to the module
    ///
    /// \param module_name simple name of the module
    ///
    ///
    SSTElementPythonModuleCode* addSubModule(const std::string& module_name);

    //! Get the full name of the module
    /**
     *  Get the full name of the module formatted as parent_full_name.module_name.
     *  \return full name of module as a string
     */
    std::string getFullModuleName();

    virtual ~SSTElementPythonModuleCode() = default;
};

/**
   Base class for python modules in element libraries.

   Element libraries can include a class derived from this class and
   create a python module hierarchy.
 */
class SSTElementPythonModule
{

protected:
    std::string library;
    std::string pylibrary;
    std::string sstlibrary;
    char*       primary_module;

    std::vector<std::pair<std::string, char*>> sub_modules;

    SSTElementPythonModuleCode* primary_code_module;

    // Only needed for supporting the old ELI
    SSTElementPythonModule() {}

public:
    SST_ELI_DECLARE_BASE(SSTElementPythonModule)
    SST_ELI_DECLARE_DEFAULT_INFO_EXTERN()
    SST_ELI_DECLARE_CTOR_EXTERN(const std::string&)

    virtual ~SSTElementPythonModule() {}

    //! Constructor for SSTElementPythonModule.  Must be called by derived class
    /**
     * \param library name of the element library the module is part
     * of.  Primary module name will be sst.library and submodules
     * under this can also be created.
     */
    explicit SSTElementPythonModule(const std::string& library);

    virtual void* load();

    //! Create the top level python module (i.e. the one named sst.library)
    /// Python files will need to be turned into a char array (code parameter).  One way to do
    /// this is to use the following in your Makefile:
    /// \verbatim %.inc: %.py
    ///         od -v -t x1 < $< | sed -e 's/^[^ ]*[ ]*//g' -e '/^\s*$$/d' -e 's/\([0-9a-f]*\)[ $$]*/0x\1,/g' > $@
    ///         \endverbatim
    /// \param code code to be compiled
    /// \param filename filname used when reporting errors
    ///
    ///
    SSTElementPythonModuleCode* createPrimaryModule(char* code, const std::string& filename);

    //! Create and empty top level python module (i.e. the one named sst.library)
    ///
    ///
    SSTElementPythonModuleCode* createPrimaryModule();
};

} // namespace SST

#define SST_ELI_REGISTER_PYTHON_MODULE(cls, lib, version) \
    SST_ELI_REGISTER_DERIVED(SST::SSTElementPythonModule,cls,lib,lib,ELI_FORWARD_AS_ONE(version),"Python module " #cls)

#endif // SST_CORE_MODEL_ELEMENT_PYTHON_H