Install & Usage of Cytnx

To install Cytnx, we recommend user to use anaconda/miniconda to install. However, advanced users can also build from source if necessary. Note that both Python API and C++ API will be installed together regardless of which method you use.

Conda install

In the following we show how to install Cytnx with conda.

  1. Install Anaconda3 / Miniconda3.

  2. Create a virtual environment:

  • For linux/WSL:

1$conda config --add channels conda-forge
2$conda create --channel conda-forge --name cytnx python=3.9 _openmp_mutex=*=*_llvm

Note

  1. We do not support a native Windows package at this stage. If you are using Windows OS, please use WSL.

  2. Currently, the supported Python versions are updated to: linux – 3.9+; MacOS-osx64 – 3.9+ (no conda support). You can change the python=* argument to the version you like.

  • For MacOS:

    Please build from source, currently 0.9+ does not have conda package support.

Note

  • See This page for how to use virtual environment in conda.

  1. Activate environment and conda install the cytnx package:

    Once you create a virtual environment, we need to activate the environment before starting to use it.

$conda activate cytnx

$conda install -c kaihsinwu cytnx

Note

  • To install the GPU (CUDA) support version, use:

$conda install -c kaihsinwu cytnx_cuda

Once it is installed, we are all set, and ready to start using Cytnx.

Using Python API after Conda install

After installing Cytnx, using the Python API is very straight forward, simply import cytnx via:

  • In Python:

1import cytnx
2
3A = cytnx.ones(4)
4print(A)

Output>>

Total elem: 4
type  : Double (Float64)
cytnx device: CPU
Shape : (4)
[1.00000e+00 1.00000e+00 1.00000e+00 1.00000e+00 ]

Using C++ API after Conda install

One important feature of Cytnx is that the installation also provides a C++ API. There are fundamental differences between C++ and Python, where C++ requires compiling and linking of the code, while Python as an interpreted language does not require both steps.

Cytnx provides a simple way for users to easily compile their C++ code. In the cytnx package, we provide three pre-set variables:

  • In Python:

1import cytnx
2cytnx.__cpp_include__
3cytnx.__cpp_lib__
4cytnx.__cpp_linkflags__
5cytnx.__cpp_flags__

  • The first one cytnx.__cpp_include__ gives you the cytnx header files directory path.

  • The second one cytnx.__cpp_lib__ gives you the cytnx library file directory path.

  • The third one cytnx.__cpp_linkflags__ gives you the essential linking flags that are required when you link your own programs that using cytnx.

  • The fourth one cytnx.__cpp_flags__ gives you the essential compiling flags that are required when you link your own programs that use cytnx.

Let us consider the same example as before for Python. Here, we want to compile the test.cpp that uses Cytnx:

  • test.cpp; in C++:

 1#include "cytnx.hpp"
 2#include <iostream>
 3using namespace std;
 4using namespace cytnx;
 5
 6int main(){
 7    auto A = zeros(4);
 8    cout << A << endl;
 9    return 0;
10}

Now, to compile and link the above test.cpp which produces an executable test, we can simply use the following bash script:

1export CYTNX_INC=$(python -c "exec(\"import cytnx\nprint(cytnx.__cpp_include__)\")")
2export CYTNX_LIB=$(python -c "exec(\"import cytnx\nprint(cytnx.__cpp_lib__)\")")/libcytnx.a
3export CYTNX_LINK="$(python -c "exec(\"import cytnx\nprint(cytnx.__cpp_linkflags__)\")")"
4export CYTNX_CXXFLAGS="$(python -c "exec(\"import cytnx\nprint(cytnx.__cpp_flags__)\")")"
5
6g++ -I${CYTNX_INC} ${CYTNX_CXXFLAGS} test.cpp ${CYTNX_LIB} ${CYTNX_LINK} -o test

The first four lines are the Python inline executions to get the three required attributes and store them into CYTNX_INC, CYTNX_LIB, CYTNX_LINK and CYTNX_CXXFLAGS variables. The last line is the usual compiling and linking of the C++ code test.cpp. After executing these steps, we can then run the program with the executable test.

./test

Output>>

Total elem: 4
type  : Double (Float64)
cytnx device: CPU
Shape : (4)
[1.00000e+00 1.00000e+00 1.00000e+00 1.00000e+00 ]

For users who what to use cmake/make to integrate Cytnx into more complex projects, one can use the following lines to extract the essential variables for cmake:

CYTNX_INC := $(shell python -c "exec(\"import cytnx\nprint(cytnx.__cpp_include__)\")")
CYTNX_LDFLAGS := $(shell python -c "exec(\"import cytnx\nprint(cytnx.__cpp_linkflags__)\")")
CYTNX_LIB := $(shell python -c "exec(\"import cytnx\nprint(cytnx.__cpp_lib__)\")")/libcytnx.a
CYTNX_CXXFLAGS := $(shell python -c "exec(\"import cytnx\nprint(cytnx.__cpp_flags__)\")")