pybind11_examples
1.0.0
Kekuatan Pybind11 ditangkap oleh kutipan berikut dari ReadMe Pybind11:
PyBind11 adalah perpustakaan yang hanya header ringan yang memperlihatkan jenis C ++ dalam Python dan sebaliknya, terutama untuk membuat binding python dari kode C ++ yang ada. Tujuan dan sintaksnya mirip dengan perpustakaan Boost.python yang sangat baik oleh David Abrahams ...
Masalah utama dengan boost.python - dan alasan untuk membuat proyek serupa - adalah Boost. Boost adalah rangkaian perpustakaan utilitas yang sangat besar dan kompleks yang bekerja dengan hampir setiap kompiler C ++ yang ada. ... Sekarang kompiler C ++ 11 yang kompatibel tersedia secara luas, mesin berat ini telah menjadi ketergantungan yang terlalu besar dan tidak perlu.
Repositori ini berisi beberapa contoh untuk penggunaan Pybind11. Meskipun dokumentasi online yang disediakan oleh pengembang Pybind11 membuat penggunaannya relatif mudah, beberapa contoh - seperti yang disediakan di sini - membuat Pybind11 lebih mudah digunakan. Contoh -contoh ini dimaksudkan untuk Anda mulai lebih cepat dengan Pybind11. Mereka, bagaimanapun, sama sekali tidak lengkap, dan tidak selalu memberikan pilihan optimal. Oleh karena itu sangat disarankan untuk berpikir sendiri . Selain itu, kontribusi dengan contoh sederhana yang serupa (atau dengan lebih meningkatkan contoh yang ada) sangat disambut . Silakan mengajukan permintaan tarik atau masalah di GitHub, atau hubungi saya.
Untuk memberikan kredit di mana kredit jatuh tempo:
Pencipta Pybind11 telah melakukan pekerjaan dengan baik! Sangat mudah digunakan, dan sangat ringan. Dokumentasi juga sudah cukup lengkap.
Contoh -contoh yang disediakan oleh Cliburn Chan dan Janice McCarthy, di Duke University sangat membantu. Tolong juga membaca dokumentasi mereka.
Perhatikan bahwa ada juga kasus uji yang ganda sebagai contoh dalam repositori Pybind11, tetapi ini tidak terlalu berwawasan saat Anda baru di Pybind11.
Akhirnya, PyBind11 digunakan secara aktif. Jadi orang dapat melihat di perpustakaan yang dikelola secara aktif untuk solusi tertentu. Misalnya:
Modul PyBind11 (yang hanya header!) Termasuk sebagai submodul dari repositori ini. Ini membutuhkan perhatian saat mengkloning proyek ini. Ada dua opsi:
Opsi paling sederhana adalah:
git clone --recursive https://github.com/tdegeus/pybind11_examples.gitIni akan mengunduh submodule hingga versi yang digunakan dalam proyek ini. Untuk memperbarui komitmen terbaru dari submodule itu sendiri:
git submodule update --remoteSeseorang juga dapat secara langsung mengunduh submodule dari sumbernya:
git clone https://github.com/tdegeus/pybind11_examples.git
cd pybind11_examples
git submodule init
git submodule updatePerpustakaan Eigen digunakan dalam beberapa contoh Numpy. Dari contoh -contoh ini dapat diamati bahwa melalui pybind11, eigen dan numpy benar -benar modul jabat tangan. Hampir tidak ada kode yang diperlukan untuk membuat antarmuka C ++/Python. Perhatikan bahwa sebagian besar kesederhanaan tergantung pada salinan yang dilewati, beberapa perhatian diperlukan jika seseorang ingin lulus murni dengan referensi.
Eigen tidak perlu instalasi karena itu juga header saja. Seseorang hanya perlu mengunduh file dan menyertakan header pada waktu kompilasi.
Secara umum orang dapat mengunduh dan menginstal eigen dengan:
mkdir /path/to/temp/build
cmake /path/to/eigen/download
make installUntuk macOS orang bisa menggunakan
brew install eigen
Setelah itu dikompilasi dengan
clang++ -I/path/to/eigen/instalation ...Perhatikan bahwa, ketika dikonfigurasi dengan benar (yang biasanya terjadi), pkg-config dapat digunakan untuk melacak jalur:
clang++ ` pkg-config --cflags eigen3 ` ...Atau seseorang dapat menggunakan cmake (lihat di bawah).
Jika Anda memiliki perpustakaan sederhana, Anda mungkin ingin melakukan semuanya sendiri. Dalam hal ini Anda mengkompilasi sumber C ++ Anda ke objek bersama yang ditautkan ke Python. Ini bermuara pada
c++ -O3 -shared -std=gnu++11 -I ./pybind11/include ` python3-config --cflags --ldflags --libs ` example.cpp -o example.so -fPIC Aplikasi PyBind11 dapat dikompilasi dengan sangat mudah menggunakan CMake. Untuk kesederhanaan pybind11 dimasukkan sebagai sub-folder dari contoh di bawah ini (pada kenyataannya menggunakan tautan simbolis ke lebih dari banyak salinan), sehingga kita dapat menggunakan CMakeLists.txt like:
cmake_minimum_required ( VERSION 2.8.12)
project (example)
add_subdirectory (pybind11)
pybind11_add_module(example example.cpp) (Di mana modul contoh ini terdiri dari satu file sumber example.cpp ). Untuk mengkompilasinya, gunakan:
cd /path/to/build
cmake /path/to/example/src
make Ketika eigen 'diinstal' dapat dengan mudah disertakan dengan menambahkan yang berikut di CMakeLists.txt :
find_package ( PkgConfig )
pkg_check_modules( EIGEN3 REQUIRED eigen3 )
include_directories ( ${EIGEN3_INCLUDE_DIRS} ) Standar C ++ 14 dapat digunakan dengan memasukkan yang berikut ini di CMakeLists.txt :
set (CMAKE_CXX_STANDARD 14) File setup.py dapat ditambahkan ke perpustakaan Anda. Anda kemudian dapat mengkompilasi dan menginstal menggunakan
python3 setup.py build
python3 setup.py install Meskipun menulis setup.py tidak sulit, itu tidak tercakup di sini. Seseorang dapat menggunakan beberapa alat yang termasuk dalam CPPMAT, yang dapat dipasang dengan PIP (misalnya pip3 install cppmat ). Selanjutnya dapat melihat setup.py misalnya Goosetensor atau beberapa repositori saya lainnya.
Contoh ini menampilkan satu fungsi modify yang mengambil daftar (read-only), melipatgandakan semua entri dengan dua, dan mengembalikannya sebagai daftar ganda (lihat example.cpp ). Dari Python fungsi ini terkandung dalam example modul sederhana (lihat test.py ).
Tujuan dari contoh ini adalah untuk menunjukkan cara membuat fungsi menerima daftar, cara mengonversi ini ke standar c ++ std::vector , dan cara mengembalikan std::vector (atau daftar) baru. Perhatikan bahwa operasi yang sebenarnya tidak terlalu penting, itu adalah antarmuka yang diilustrasikan.
Untuk dikompilasi, baik menggunakan cmake, di mana instruksi kompilasi dibaca dari CMakeLists.txt selanjutnya:
cmake .
makeAtau, kompilasi langsung menggunakan:
c++ -O3 -shared -std=gnu++11 -I ./pybind11/include ` python3-config --cflags --ldflags --libs ` example.cpp -o example.so -fPICJalankan contoh dengan:
python3 test.pyUntuk menjalankan dengan Python 2, cukup ganti dua kejadian "Python3" di atas dengan "Python". Untuk memodifikasi instruksi cmake, temukan lebih banyak online.
Sama seperti contoh sebelumnya, tetapi dengan daftar bersarang.
Fungsi modify yang mengubah entri dari array satu dimensi menjadi bilangan bulat, dan kemudian melipatgandakan entri ini dengan 10.
Tujuan dari contoh ini adalah untuk menunjukkan cara membuat fungsi menerima array numpy satu dimensi, cara mengonversi ini ke standar C ++ std::vector , dan cara mengembalikan array numpy satu dimensi. Perhatikan bahwa antarmuka yang dihasilkan menggunakan PyBind11 sangat fleksibel sehingga bahkan menerima daftar input di sisi Python.
Satu length fungsi. Fungsi ini menerima 'matriks' di mana terdiri dari daftar vektor posisi 2-D, sebagai baris. Hasilnya lagi adalah 'matriks' dengan untuk setiap baris posisi "x" dan "y", dan panjang vektor posisi 2-D.
Dua fungsi det dan inv yang menggunakan pustaka eigen.
Tujuan dari contoh ini adalah untuk menunjukkan betapa sepele interaksi antara C ++/Eigen dan Python/Numpy.
Untuk mengkompilasi menggunakan cmake dan untuk dijalankan, ikuti instruksi di atas (di mana header eigen termasuk dalam CMakeLists.txt . Untuk mengkompilasi secara langsung, juga header eigen harus disertakan:
c++ -O3 -shared -std=gnu++11 -I /path/to/eigen -I ./pybind11/include ` python3-config --cflags --ldflags --libs ` example.cpp -o example.so -fPICMisalnya pada macOS dengan homebrew:
c++ -O3 -shared -std=gnu++11 -I /usr/local/Cellar/eigen/3.3.1/include/eigen3 -I ./pybind11/include ` python3-config --cflags --ldflags --libs ` example.cpp -o example.so -fPIC Kelas CustomVectorXd khusus dengan satu fungsi mul . Kelas ini menggunakan perpustakaan eigen. Ini juga termasuk argumen default.
Selain itu, contoh ini memiliki fungsi trans (sama sekali tidak terkait dengan kelas CustomVectorXd khusus). Tujuannya adalah untuk menunjukkan cara mengembalikan Eigen::VectorXi (atau numpy-array).
Satu fungsi yang kelebihan beban mul . Fungsi ini bertindak 'berbeda' jika dipanggil dengan argumen int atau argumen double . Perhatikan bahwa perilaku default Pybind11 cukup kuat. Saat memanggil fungsi dengan satu int dan satu argumen double , modul akan memilih versi double mul (dan akan memberikan argumen int ke double ).
Untuk dikompilasi, pastikan bahwa standar C ++ 14 digunakan, misalnya dengan memasukkan -std=c++14 sebagai argumen kompiler.
Mirip dengan contoh sebelumnya, tetapi dengan argumen eigen (yaitu argumen numpy dari sisi Python).
Untuk dikompilasi, pastikan standar C ++ 14 digunakan.
Contoh ini termasuk kelas matriks khusus di C ++ (dalam matrix.h ). Kelas ini digabungkan ke array numpy menggunakan antarmuka sederhana (di pybind_matrix.h ). Akibatnya fungsi (dalam example.cpp ) tidak memerlukan kode pembungkus khusus.
Lihat juga diskusi Stack Overflow ini.
Contoh ini menampilkan cara untuk berinteraksi dengan enumerator di C ++. Pada prinsipnya antarmuka sangat mudah tetapi menjamin 'trik'. Di sini submodule digunakan untuk dapat berinteraksi dengan enumerator dengan cara yang sama seperti di C ++.
Contoh ini berisi contoh klasik di mana satu atau lebih kelas berasal dari orang tua atau templat tertentu. Contoh khusus ini berisi dua hewan, seekor Dog dan Cat , yang keduanya berasal dari kelas Animal generik. Ada fungsi talk yang menerima Animal generik dan dengan demikian kelas yang diturunkan.
Kasus khusus ini membutuhkan antarmuka yang lebih terlibat, seperti yang dijelaskan dalam dokumentasi.
Contoh ini menampilkan CRTP sederhana dengan sebagai 'pangkalan' dan dan kelas 'turunan', dan pendaftarannya ke API Pybind11 .
Terkadang py::overload_cast tidak dapat menyelesaikan fungsi Anda, misalnya ketika tipe pengembalian tidak dapat disimpulkan. Dalam hal ini Anda dapat eksplisit dengan static_cast ing pointer ke fungsi Anda lebih banyak informasi dapat ditemukan dalam dokumentasi.
