PyArrayAccessor.cc

Go to the documentation of this file.

// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
 
#include "PyArrayAccessor.h"
 
#include <ChimeraTK/PyConvert.h>
 
#include <pybind11/stl.h>
 
namespace py = pybind11;
 
namespace ChimeraTK {
 
  /********************************************************************************************************************/
 
  template<template<typename> class AccessorType>
  ArrayAccessorVariant PyArrayAccessor::createAccessor(ChimeraTK::DataType type, Module* owner, const std::string& name,
      std::string unit, size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
    std::optional<ArrayAccessorVariant> rv;
    ChimeraTK::callForTypeNoVoid(type, [&](auto t) {
      using UserType = decltype(t);
      AccessorType<UserType> acc(owner, name, unit, nElements, description, tags);
      rv.emplace(std::in_place_type<AccessorType<UserType>>, std::move(acc));
    });
    return std::move(rv.value());
  }
 
  /********************************************************************************************************************/
 
  py::object PyArrayAccessor::readAndGet() {
    read();
    return get();
  }
 
  /********************************************************************************************************************/
 
  void PyArrayAccessor::setAndWrite(const pybind11::object& input) {
    set(input);
    write();
  }
  /********************************************************************************************************************/
 
  size_t PyArrayAccessor::getNElements() {
    size_t rv;
    std::visit([&](auto& acc) { rv = acc.getNElements(); }, _accessor);
    return rv;
  }
 
  /********************************************************************************************************************/
 
  void PyArrayAccessor::set(const py::object& input) {
    std::visit(
        [&](auto& acc) {
          using ACC = std::remove_reference<decltype(acc)>::type;
          using expectedUserType = ACC::value_type;
          std::vector<expectedUserType> converted = convertPyObject<expectedUserType>(input, false, true);
          acc = converted;
        },
        _accessor);
  }
 
  /********************************************************************************************************************/
 
  py::object PyArrayAccessor::get() const {
    py::object rv;
    std::visit(
        [&](auto& acc) {
          using ACC = typename std::remove_reference<decltype(acc)>::type;
          using userType = typename ACC::value_type;
          auto ndacc = boost::dynamic_pointer_cast<NDRegisterAccessor<userType>>(acc.getHighLevelImplElement());
          if constexpr(std::is_same<userType, std::string>::value) {
            // String arrays are not really supported by numpy, so we return a list instead
            rv = py::cast(ndacc->accessChannel(0));
          }
          else {
            auto ary = py::array(py::dtype::of<userType>(), {acc.getNElements()}, {sizeof(userType)},
                ndacc->accessChannel(0).data(), py::cast(this));
            assert(!ary.owndata()); // numpy must not own our buffers
            rv = ary;
          }
        },
        _accessor);
    return rv;
  }
  /********************************************************************************************************************/
 
  py::object PyArrayAccessor::getitem(size_t index) const {
    py::object rv;
    // Return the element as a numpy scalar of the matching user type (e.g. np.float32)
    // so that single-element access is consistent with get().
    std::visit(
        [&](auto& acc) {
          using ACC = std::remove_reference<decltype(acc)>::type;
          using userType = typename ACC::value_type;
          auto ndacc = boost::dynamic_pointer_cast<NDRegisterAccessor<userType>>(acc.getHighLevelImplElement());
          if constexpr(std::is_same<userType, std::string>::value) {
            // String arrays are not really supported by numpy, so we return a python string
            rv = py::cast(ndacc->accessChannel(0)[index]);
          }
          else {
            // Create a 1-element numpy array of the correct dtype pointing to this element and index it,
            // so numpy returns the matching numpy scalar type (np.float32, np.int32, ...).
            auto ary = py::array(
                py::dtype::of<userType>(), {1}, {sizeof(userType)}, &ndacc->accessChannel(0)[index], py::cast(this));
            assert(!ary.owndata()); // numpy must not own our buffers
            rv = ary.attr("__getitem__")(py::int_(0));
          }
        },
        _accessor);
    return rv;
  }
 
  /********************************************************************************************************************/
 
  void PyArrayAccessor::setitem(size_t index, const pybind11::object& input) {
    std::visit(
        [&](auto& acc) {
          using ACC = std::remove_reference<decltype(acc)>::type;
          using expectedUserType = ACC::value_type;
 
          // TODO check whether we can disable Pass 2 of python argument conversion also for setitem,setslice
          expectedUserType value = convertPyScalar<expectedUserType>(input);
          acc[index] = value;
        },
        _accessor);
  }
 
  /********************************************************************************************************************/
 
  void PyArrayAccessor::setslice(const py::slice& slice, const pybind11::object& input) {
    std::visit(
        [&](auto& acc) {
          size_t start, stop, step, length;
          if(!slice.compute(acc.getNElements(), &start, &stop, &step, &length)) {
            throw pybind11::error_already_set();
          }
          using ACC = std::remove_reference<decltype(acc)>::type;
          using expectedUserType = ACC::value_type;
          expectedUserType value = convertPyScalar<expectedUserType>(input);
          for(size_t i = start; i < stop; i += step) {
            acc[i] = value;
          }
        },
        _accessor);
  }
 
  /********************************************************************************************************************/
 
  std::string PyArrayAccessor::repr(py::object& acc) {
    if(not acc.cast<PyArrayAccessor&>().getTE().isInitialised()) {
      return "<ArrayAccessor(not initialized)>";
    }
 
    std::string rep{"<ArrayAccessor(type="};
    rep.append(py::cast<py::object>(py::cast(&acc).attr("getValueType")()).attr("__repr__")().cast<std::string>());
    rep.append(", name=");
    rep.append(py::cast(&acc).attr("getName")().cast<std::string>());
    rep.append(", data=");
    rep.append(py::cast<py::object>(py::cast(&acc).attr("__str__")()).cast<std::string>());
    rep.append(", versionNumber=");
    rep.append(py::cast<py::object>(py::cast(&acc).attr("getVersionNumber")()).attr("__repr__")().cast<std::string>());
    rep.append(", dataValidity=");
    rep.append(py::cast<py::object>(py::cast(&acc).attr("dataValidity")()).attr("__repr__")().cast<std::string>());
    rep.append(")>");
    return rep;
  }
  /********************************************************************************************************************/
 
  py::buffer_info PyArrayAccessor::getBufferInfo() {
    py::buffer_info info;
    std::visit(
        [&](auto& acc) {
          using ACC = typename std::remove_reference<decltype(acc)>::type;
          using userType = typename ACC::value_type;
          auto ndacc = boost::dynamic_pointer_cast<NDRegisterAccessor<userType>>(acc.getHighLevelImplElement());
          if constexpr(std::is_same<userType, ChimeraTK::Boolean>::value) {
            info.format = py::format_descriptor<bool>::format();
          }
          else if constexpr(std::is_same<userType, std::string>::value) {
            // cannot implement
            return;
          }
          else {
            info.format = py::format_descriptor<userType>::format();
          }
          info.ptr = ndacc->accessChannel(0).data();
          info.itemsize = sizeof(userType);
          info.ndim = 1;
          info.shape = {acc.getNElements()};
          info.strides = {sizeof(userType)};
        },
        _accessor);
    return info;
  }
 
  /********************************************************************************************************************/
 
  PyArrayAccessor::~PyArrayAccessor() = default;
 
  /********************************************************************************************************************/
 
  void PyArrayAccessor::bind(py::module& m) {
    py::class_<PyArrayAccessor, PyTransferElementBase, std::unique_ptr<PyArrayAccessor, py::nodelete>> arrayacc(
        m, "ArrayAccessor", py::buffer_protocol(), py::module_local());
    arrayacc.def(py::init<>())
        .def_buffer(&PyArrayAccessor::getBufferInfo)
        .def("read", &PyArrayAccessor::read,
            "Read the data from the device.\n\nIf AccessMode::wait_for_new_data was set, this function will block "
            "until new data has arrived. Otherwise it still might block for a short time until the data transfer was "
            "complete.")
        .def("readNonBlocking", &PyArrayAccessor::readNonBlocking,
            "Read the next value, if available in the input buffer.\n\nIf AccessMode::wait_for_new_data was set, this "
            "function returns immediately and the return value indicated if a new value was available (true) or not "
            "(false).\n\nIf AccessMode::wait_for_new_data was not set, this function is identical to read(), which "
            "will still return quickly. Depending on the actual transfer implementation, the backend might need to "
            "transfer data to obtain the current value before returning. Also this function is not guaranteed to be "
            "lock free. The return value will be always true in this mode.")
        .def("readLatest", &PyArrayAccessor::readLatest,
            "Read the latest value, discarding any other update since the last read if present.\n\nOtherwise this "
            "function is identical to readNonBlocking(), i.e. it will never wait for new values and it will return "
            "whether a new value was available if AccessMode::wait_for_new_data is set.")
        .def("write", &PyArrayAccessor::write,
            "Write the data to device.\n\nThe return value is true, old data was lost on the write transfer (e.g. due "
            "to an buffer overflow). In case of an unbuffered write transfer, the return value will always be false.")
        .def("writeDestructively", &PyArrayAccessor::writeDestructively,
            "Just like write(), but allows the implementation to destroy the content of the user buffer in the "
            "process.\n\nThis is an optional optimisation, hence there is a default implementation which just calls "
            "the normal doWriteTransfer(). In any case, the application must expect the user buffer of the "
            "TransferElement to contain undefined data after calling this function.")
        .def("getName", &PyArrayAccessor::getName, "Returns the name that identifies the process variable.")
        .def("getUnit", &PyArrayAccessor::getUnit,
            "Returns the engineering unit.\n\nIf none was specified, it will default to ' n./ a.'")
        .def("getDescription", &PyArrayAccessor::getDescription, "Returns the description of this variable/register.")
        .def("getValueType", &PyArrayAccessor::getValueType,
            "Returns the std::type_info for the value type of this transfer element.\n\nThis can be used to determine "
            "the type at runtime.")
        .def("getVersionNumber", &PyArrayAccessor::getVersionNumber,
            "Returns the version number that is associated with the last transfer (i.e. last read or write)")
        .def("isReadOnly", &PyArrayAccessor::isReadOnly,
            "Check if transfer element is read only, i.e. it is readable but not writeable.")
        .def("isReadable", &PyArrayAccessor::isReadable, "Check if transfer element is readable.")
        .def("isWriteable", &PyArrayAccessor::isWriteable, "Check if transfer element is writeable.")
        .def("getId", &PyArrayAccessor::getId,
            "Obtain unique ID for the actual implementation of this TransferElement.\n\nThis means that e.g. two "
            "instances of ScalarRegisterAccessor created by the same call to Device::getScalarRegisterAccessor() (e.g. "
            "by copying the accessor to another using NDRegisterAccessorBridge::replace()) will have the same ID, "
            "while two instances obtained by to difference calls to Device::getScalarRegisterAccessor() will have a "
            "different ID even when accessing the very same register.")
        .def("dataValidity", &PyArrayAccessor::dataValidity,
            "Return current validity of the data.\n\nWill always return DataValidity.ok if the backend does not "
            "support it")
        .def("getNElements", &PyArrayAccessor::getNElements, "Return number of elements/samples in the register.")
        .def("get", &PyArrayAccessor::get, "Return an array of UserType (without a previous read).")
        .def("set", &PyArrayAccessor::set, "Set the values of the array of UserType.", py::arg("newValue"))
        .def("setAndWrite", &PyArrayAccessor::setAndWrite,
            "Convenience function to set and write new value.\n\nThe given version number. If versionNumber == {}, a "
            "new version number is generated.",
            py::arg("newValue"))
        .def(
            "readAndGet", &PyArrayAccessor::readAndGet, "Convenience function to read and return an array of UserType.")
        .def("__repr__", &PyArrayAccessor::repr)
        .def("__getitem__", &PyArrayAccessor::getitem)
        .def("__setitem__", &PyArrayAccessor::setitem, "", py::arg("index"), py::arg("newValue"))
        .def("__setitem__", &PyArrayAccessor::setslice, "", py::arg("slice"), py::arg("newValue"))
        .def("__getattr__", &PyArrayAccessor::getattr);
    for(const auto& fn : PyTransferElementBase::specialFunctionsToEmulateNumeric) {
      arrayacc.def(fn.c_str(),
          [fn](PyArrayAccessor& acc, PyArrayAccessor& other) { return acc.get().attr(fn.c_str())(other.get()); });
      arrayacc.def(
          fn.c_str(), [fn](PyArrayAccessor& acc, py::object& other) { return acc.get().attr(fn.c_str())(other); });
    }
    for(const auto& fn : PyTransferElementBase::specialUnaryFunctionsToEmulateNumeric) {
      arrayacc.def(fn.c_str(), [fn](PyArrayAccessor& acc) { return acc.get().attr(fn.c_str())(); });
    }
 
    m.def(
        "ArrayPushInput",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInput>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayPushInput",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInput>{}, DataType(type), &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayPushInputWB",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInputWB>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayPushInputWB",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInputWB>{}, DataType(type), &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayPollInput",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPollInput>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayPollInput",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPollInput>{}, DataType(type), &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayOutput",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutput>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayOutput",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutput>{}, DataType(type), &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayOutputPushRB",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutputPushRB>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayOutputPushRB",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutputPushRB>{}, DataType(type), &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayOutputReverseRecovery",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutputReverseRecovery>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayOutputReverseRecovery",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayOutputReverseRecovery>{}, DataType(type), &owner, name, unit, nElements, description,
              tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayPushInputNoInitialValue",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInputNoInitialValue>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayPushInputNoInitialValue",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPushInputNoInitialValue>{}, DataType(type), &owner, name, unit, nElements,
              description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
 
    m.def(
        "ArrayPollInputNoInitialValue",
        [](ChimeraTK::DataType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPollInputNoInitialValue>{}, type, &owner, name, unit, nElements, description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
    m.def(
        "ArrayPollInputNoInitialValue",
        [](ChimeraTK::DataType::TheType type, VariableGroup& owner, const std::string& name, const std::string& unit,
            size_t nElements, const std::string& description, const std::unordered_set<std::string>& tags) {
          return dynamic_cast<PyOwningObject&>(owner).make_child<PyArrayAccessor>(
              AccessorTypeTag<ArrayPollInputNoInitialValue>{}, DataType(type), &owner, name, unit, nElements,
              description, tags);
        },
        py::arg("type"), py::arg("owner"), py::arg("name"), py::arg("unit"), py::arg("nElements"),
        py::arg("description"), py::arg("tags") = std::unordered_set<std::string>{}, py::return_value_policy::reference,
        "");
  }
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK