Merge pull request #171 from qulacs/170-googlestyle-docstring

Google Style Docstring

doc/source/conf.py

@@ -23,7 +23,7 @@
 autoapi_dirs = ["./stub/scaluq"]
 autoapi_add_toctree_entry = True
 
-autoapi_python_class_content = 'both'
+autoapi_python_class_content = 'class'
 autoapi_options = [
     "members",
     "undoc-members",

main.py

@@ -0,0 +1,4 @@
+from scaluq import StateVector
+
+state = StateVector(2)
+state.get_amplitude_at(2)

python/binding.cpp

@@ -13,6 +13,8 @@
 #include <nanobind/stl/variant.h>
 #include <nanobind/stl/vector.h>
 
+#include "docstring.hpp"
+
 namespace nb = nanobind;
 using namespace nb::literals;
 

python/docstring.hpp

@@ -0,0 +1,133 @@
+#include <optional>
+#include <ranges>
+#include <sstream>
+#include <variant>
+#include <vector>
+
+class DocString {
+public:
+    using Code = std::vector<std::string>;
+    using Block = std::variant<std::string, Code>;
+    using Blocks = std::vector<Block>;
+    struct Arg {
+        std::string name;
+        std::string type;
+        bool is_optional;
+        Blocks description;
+    };
+    struct Ret {
+        std::string type;
+        Blocks description;
+    };
+
+    explicit DocString() {}
+    DocString& desc(const Block& desc) {
+        description.push_back(desc);
+        return *this;
+    }
+    DocString& arg(const Arg& arg) {
+        args.push_back(arg);
+        return *this;
+    }
+    template <class... Args>
+    DocString& arg(std::string_view name, std::string_view type, const Args&... desc) {
+        args.push_back(Arg(std::string(name), std::string(type), false, construct_blocks(desc...)));
+        return *this;
+    }
+    template <class... Args>
+    DocString& arg(std::string_view name,
+                   std::string_view type,
+                   bool is_optional,
+                   const Args&... desc) {
+        args.push_back(
+            Arg(std::string(name), std::string(type), is_optional, construct_blocks(desc...)));
+        return *this;
+    }
+    DocString& ret(const Ret& ret) {
+        returns = ret;
+        return *this;
+    }
+    template <class... Args>
+    DocString& ret(std::string_view type, const Args&... desc) {
+        returns = Ret(std::string(type), construct_blocks(desc...));
+        return *this;
+    }
+    DocString& ex(const Block& ex) {
+        examples.push_back(ex);
+        return *this;
+    }
+    DocString& note(const Block& note) {
+        notes.push_back(note);
+        return *this;
+    }
+
+    std::string build_as_google_style() {
+        std::ostringstream out;
+        auto output = [&](const Block& b, std::string_view indent) {
+            if (b.index() == 0) {
+                out << indent << std::get<0>(b) << "\n\n";
+            } else {
+                const auto& code = std::get<1>(b);
+                for (const auto& line : code) {
+                    out << indent << line << "\n";
+                }
+                out << "\n";
+            }
+        };
+        for (const auto& b : description) {
+            output(b, "");
+        }
+        if (!args.empty()) {
+            out << "Args:\n";
+            for (const auto& arg : args) {
+                out << "    " << arg.name << " (" << arg.type
+                    << (arg.is_optional ? ", optional):\n" : "):\n");
+                for (const auto& b : arg.description) {
+                    output(b, "        ");
+                }
+            }
+        }
+        if (returns.has_value()) {
+            out << "Returns:\n";
+            const auto& ret = returns.value();
+            out << "    " << ret.type << ":\n";
+            for (const auto& b : ret.description) {
+                output(b, "        ");
+            }
+        }
+        if (!examples.empty()) {
+            out << "Examples:\n";
+            for (const auto& b : examples) {
+                output(b, "    ");
+            }
+        }
+        if (!notes.empty()) {
+            out << "Notes:\n";
+            for (const auto& b : notes) {
+                output(b, "    ");
+            }
+        }
+        return out.str();
+    }
+
+private:
+    Blocks description;
+    std::vector<Arg> args;
+    std::optional<Ret> returns;
+    Blocks examples;
+    Blocks notes;
+
+    Blocks construct_blocks_reverse() { return Blocks(); }
+    template <class... Tail>
+    Blocks construct_blocks_reverse(const Block& block, const Tail&... tail) {
+        Blocks blocks = construct_blocks_reverse(tail...);
+        blocks.push_back(block);
+        return blocks;
+    }
+    template <class... Args>
+    Blocks construct_blocks(const Args&... args) {
+        Blocks blocks = construct_blocks_reverse(args...);
+        std::ranges::reverse(blocks);
+        return blocks;
+    }
+};

scaluq/state/state_vector.cpp

@@ -12,9 +12,9 @@ StateVector::StateVector(std::uint64_t n_qubits)
     set_zero_state();
 }
 
-void StateVector::set_amplitude_at(std::uint64_t index, const Complex& c) {
+void StateVector::set_amplitude_at(std::uint64_t index, const Complex& value) {
     Kokkos::View<Complex, Kokkos::HostSpace> host_view("single_value");
-    host_view() = c;
+    host_view() = value;
     Kokkos::deep_copy(Kokkos::subview(_raw, index), host_view());
 }
 
@@ -156,7 +156,7 @@ double StateVector::get_entropy() const {
         KOKKOS_CLASS_LAMBDA(std::uint64_t idx, double& lsum) {
             double prob = internal::squared_norm(_raw[idx]);
             prob = (prob > eps) ? prob : eps;
-            lsum += -prob * Kokkos::log(prob);
+            lsum += -prob * Kokkos::log2(prob);
         },
         ent);
     return ent;