Skip to content

Commit 99a4fec

Browse files
rolandlichtersrolandlichters
committed
Merge branch 'update_docs' into 'master'
Update Docs See merge request qs/oreswig!28
2 parents 5f6cf5b + d9fc799 commit 99a4fec

8 files changed

Lines changed: 683 additions & 75 deletions

‎README‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Build using CMake on Mac OS
2424
(1) Fetch ORE (branch origin/ore_swig_cmake) and build with CMake
2525
See user guide on that branch (Docs/UserGuide/userguide.pdf), new section on page 16.
2626

27-
(2) cd ORESWIG projekt directory and pull down QuantLib-SWIG:
27+
(2) cd ORESWIG project directory and pull down QuantLib-SWIG:
2828
git submodule init
2929
git submodule update
3030

@@ -35,16 +35,16 @@ Build using CMake on Mac OS
3535
For example:
3636

3737
cmake -D PYTHON_LIBRARY=/Users/roland/anaconda/lib/libpython3.5m.dylib \
38-
-D PYTHON_INCLUDE_DIR=/Users/roland/anaconda/include/python3.5m \
39-
-D BOOST_ROOT=/Users/roland/Development/boost/boost_1_65_1 \
40-
-D BOOST_LIB=/Users/roland/Development/boost/boost_1_65_1/stage/lib \
41-
-D ORE=/Users/roland/Development/oremaster ..
38+
-D PYTHON_INCLUDE_DIR=/Users/roland/anaconda/include/python3.5m \
39+
-D BOOST_ROOT=/Users/roland/Development/boost/boost_1_65_1 \
40+
-D BOOST_LIB=/Users/roland/Development/boost/boost_1_65_1/stage/lib \
41+
-D ORE=/Users/roland/Development/oremaster ..
4242

43-
PYTHON_LIBRARY, PYTHON_INCLUDE_DIR, BOOST_ROOT and BOOST_LIB can also be set as environemnt variable,
43+
PYTHON_LIBRARY, PYTHON_INCLUDE_DIR, BOOST_ROOT and BOOST_LIB can also be set as environment variables,
4444
and need not be passed with the -D option in that case.
45-
45+
4646
(5) Build (generates Python and Java wrappers so far):
47-
make
47+
make
4848

4949
(6) Run Python example:
5050
- Update PYTHONPATH, so that Python scripts will find the new Python modules
@@ -60,14 +60,14 @@ Build using CMake on Windows
6060
============================
6161

6262
(1) - (3) See above
63-
63+
6464
(4) Configuration assuming that Ninja build system is available (equivalent to make), and Python and Boost locations are
6565
found automatically. This is the command line that works on dev104:
6666

6767
cmake -D ORE=C:/dev/roland/ore \
68-
-D CMAKE_BUILD_TYPE=Release \
69-
-D MSVC_RUNTIME=static \
70-
-G Ninja ..
68+
-D CMAKE_BUILD_TYPE=Release \
69+
-D MSVC_RUNTIME=static \
70+
-G Ninja ..
7171

7272
(5) Build:
7373
ninja

‎README.md‎

Lines changed: 69 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,15 @@ C++.
1010

1111
Similar to QuantLib-SWIG, ORE-SWIG intends to provide the means
1212
to use the ORE libraries side by side with QuantLib from a
13-
number of languages including Python, Ruby, Perl, Java and C#.
13+
number of languages including Python, Ruby, Perl, Java and C#.
14+
15+
Tutorials
16+
---------
17+
18+
For a series of in depth tutorials on installing and/or building python
19+
wrappers and wheels, please refer to this document: [Tutorials
20+
Index](tutorials.00.index.md). For a general overview on using the ORE python
21+
wrapper, continue reading below.
1422

1523
Download and usage
1624
------------------
@@ -23,8 +31,8 @@ The ORE-SWIG project directory contains QuantExt-SWIG, OREData-SWIG and
2331
OREAnalytics-SWIG folders. Within the ORE-SWIG project directory, pull
2432
in the QuantLib-SWIG project by running
2533

26-
git submodule init
27-
git submodule update
34+
git submodule init
35+
git submodule update
2836

2937
Prerequisite for building the wrappers is building the latest ORE release
3038
following the steps outlined in ORE's user guide, e.g. using CMake.
@@ -34,100 +42,98 @@ Ninja: Edit the top level CMakeLists.txt to select/deselect
3442
specific library/language folders, create a subdirectory "build",
3543
change to the build directory, and run
3644

37-
cmake \
38-
-G Ninja \
39-
-D ORE=<ORE Root Directory> \
40-
[-D BOOST_ROOT=<Top level boost include directory> ] \
41-
[-D BOOST_LIB=<Location of the compiled boost libraries> ] \
42-
[-D PYTHON_LIBRARY=<Full name including path to the 'libpython*' library> ] \
43-
[-D PYTHON_INCLUDE_DIR=<Directory that contains Python.h> ] \
44-
..
45-
ninja
46-
45+
cmake \
46+
-G Ninja \
47+
-D ORE=<ORE Root Directory> \
48+
[-D BOOST_ROOT=<Top level boost include directory> ] \
49+
[-D BOOST_LIB=<Location of the compiled boost libraries> ] \
50+
[-D PYTHON_LIBRARY=<Full name including path to the 'libpython*' library> ] \
51+
[-D PYTHON_INCLUDE_DIR=<Directory that contains Python.h> ] \
52+
..
53+
ninja
4754

4855
To build on Windows using CMake and an existing Visual Studio installation you can e.g. run
4956
this from the top-level oreswig directory
5057

51-
mkdir builddir
52-
cmake -G "Visual Studio 15 2017" \
53-
-A x64 \
54-
-D SWIG_DIR=C:\dev\swigwin\Lib \
55-
-D SWIG_EXECUTABLE=C:\dev\swigwin\swig.exe \
56-
-D ORE:PATHNAME=C:\dev\ORE\master \
57-
-D BOOST_ROOT=C:\dev\boost \
58-
-S OREAnalytics-SWIG/Python \
59-
-B builddir
60-
cmake --build builddir -v
58+
mkdir builddir
59+
cmake -G "Visual Studio 15 2017" \
60+
-A x64 \
61+
-D SWIG_DIR=C:\dev\swigwin\Lib \
62+
-D SWIG_EXECUTABLE=C:\dev\swigwin\swig.exe \
63+
-D ORE:PATHNAME=C:\dev\ORE\master \
64+
-D BOOST_ROOT=C:\dev\boost \
65+
-S OREAnalytics-SWIG/Python \
66+
-B builddir
67+
cmake --build builddir -v
6168

6269
To try e.g. an OREAnalytics Python example, update your PYTHONPATH so
6370
that it includes the directory that contains the newly built python module and
6471
associated native library (both in
6572
ORE-SWIG/build/OREAnalytics-SWIG/Python), change to
6673
ORE-SWIG/OREAnalytics-SWIG/Python/Examples and run
6774

68-
python ore.py
75+
python ore.py
6976

7077
You can also try the IPython example in the same directory: Launch
7178

72-
jupyter notebook
79+
jupyter notebook
7380

7481
wait for your browser to open, select ore.ipy from the list of files
7582
and then run all cells.
7683

7784
Also note the test suite in ORE-SWIG/OREAnalytics-SWIG/Python/test:
7885

79-
python OREAnalyticsTestSuite.py
86+
python OREAnalyticsTestSuite.py
8087

8188
When the QuantExt-SWIG and OREData-SWIG modules are built as well (edit top-level CMakeLists.txt)
8289
then similar test suites in ORE-SWIG/OREData-SWIG/Python/test and ORE-SWIG/QuantExt-SWIG/Python/test
8390
can be run
8491

85-
python OREDataTestSuite.py
86-
python QuantExtTestSuite.py
92+
python OREDataTestSuite.py
93+
python QuantExtTestSuite.py
8794

8895
To try a simple OREAnalytics Java example, change to
89-
ORE-SWIG/OREAnalytics-SWIG/Java/Examples and run
90-
91-
java -Djava.library.path=../../../build/OREAnalytics-SWIG/Java \
92-
-jar ../../../build/OREAnalytics-SWIG/Java/ORERunner.jar \
93-
Input/ore.xml
96+
ORE-SWIG/OREAnalytics-SWIG/Java/Examples and run
9497

98+
java -Djava.library.path=../../../build/OREAnalytics-SWIG/Java \
99+
-jar ../../../build/OREAnalytics-SWIG/Java/ORERunner.jar \
100+
Input/ore.xml
95101

96-
Python Bindings on Windows
102+
Python Bindings on Windows
97103
--------------------------
98104

99105
On Windows you can also use the following steps to build the Python
100106
bindings using the provided setup.py script:
101107

102-
1. Include SWIG path to the Path environment variable, e.g.
103-
set Path=%Path%;C:\swigwin-3.0.12
104-
105-
2. Add PYTHON_INCLUDE and PYTHON_LIB variables to the system environment, e.g.
106-
set PYTHON_INCLUDE="C:\Users\Name\AppData\Local\Continuum\anaconda3\include"
107-
set PYTHON_LIB="C:\Users\Name\AppData\Local\Continuum\anaconda3\libs"
108-
109-
3. Add BOOST_ROOT and BOOST_LIB variables to the system environment, e.g.
110-
set BOOST_ROOT=C:\repos\boost_1_65_1
111-
set BOOST_LIB=C:\repos\boost_1_65_1\lib\x64\lib\lib
112-
113-
4. Add ORE_DIR and QL_DIR variables to the system environment, e.g.
114-
set ORE_DIR=C:\dev\ORE
115-
116-
5. Change to directory OREAnalytics-SWIG/Python and run the following
117-
python scripts to build and install ORE Analytics Python module:
118-
cd Python
119-
python setup.py wrap
120-
python setup.py build
121-
python setup.py install
122-
123-
6. Try examples (all work):
124-
cd Examples
125-
python ore.py
126-
python swap.py
127-
python market.py
128-
python commodityforward.py
129-
python conventions.py
130-
python portfolio.py
108+
1. Include SWIG path to the Path environment variable, e.g.
109+
set Path=%Path%;C:\swigwin-3.0.12
110+
111+
2. Add PYTHON_INCLUDE and PYTHON_LIB variables to the system environment, e.g.
112+
set PYTHON_INCLUDE="C:\Users\Name\AppData\Local\Continuum\anaconda3\include"
113+
set PYTHON_LIB="C:\Users\Name\AppData\Local\Continuum\anaconda3\libs"
114+
115+
3. Add BOOST_ROOT and BOOST_LIB variables to the system environment, e.g.
116+
set BOOST_ROOT=C:\repos\boost_1_65_1
117+
set BOOST_LIB=C:\repos\boost_1_65_1\lib\x64\lib\lib
118+
119+
4. Add ORE_DIR and QL_DIR variables to the system environment, e.g.
120+
set ORE_DIR=C:\dev\ORE
121+
122+
5. Change to directory OREAnalytics-SWIG/Python and run the following
123+
python scripts to build and install ORE Analytics Python module:
124+
cd Python
125+
python setup.py wrap
126+
python setup.py build
127+
python setup.py install
128+
129+
6. Try examples (all work):
130+
cd Examples
131+
python ore.py
132+
python swap.py
133+
python market.py
134+
python commodityforward.py
135+
python conventions.py
136+
python portfolio.py
131137

132138
Contributing
133139
------------

‎tutorials.00.index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
2+
# Tutorials Index
3+
4+
This page serves as the index for a series of tutorials on using and building
5+
ORE python wrappers and wheels.
6+
7+
[Installing ORE Python Libraries and Example Scripts on Windows](tutorials.01.install_windows.md)
8+
9+
[Installing ORE Python Libraries and Example Scripts on Posix Systems (e.g. MacOS and Linux)](tutorials.02.install_posix.md)
10+
11+
[Building ORE Python Wrappers on Windows](tutorials.03.build_windows.md)
12+
13+
[Building ORE Python Wrappers on Posix Systems (e.g. MacOS and Linux)](tutorials.04.build_posix.md)
14+
15+
[Managing Wheels](tutorials.05.wheels.md)
16+

‎tutorials.01.install_windows.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
2+
# Installing ORE Python Libraries and Example Scripts on Windows
3+
4+
This tutorial is aimed at the Windows user who wants to install and use the ORE
5+
Python libraries and example scripts. No compilation is necessary.
6+
7+
[Back to tutorials index](tutorials.00.index.md)
8+
9+
## Introduction
10+
11+
In principle, the command to install ORE is simply:
12+
13+
pip install open-source-risk-engine
14+
15+
However, there are some additional considerations:
16+
17+
1) The ORE example Python scripts depend upon other Python libraries.
18+
2) If you use `pip install` to install a load of Python libraries, there is the
19+
potential to pollute your machine with outdated or incompatible libraries. It
20+
is cleaner to install Python libraries into a virtual environment.
21+
22+
Therefore, this tutorial will take a step back. Starting from a clean WIndows
23+
machine, we will install all necessary prerequisites, and then the ORE Python
24+
library itself, along with the example Python scripts. We will use a virtual
25+
environment which can be modified or deleted without affecting the rest of your
26+
computer.
27+
28+
## Python
29+
30+
You need to download and install Python. You need at least Python version 3.8.
31+
To verify that you have Python installed correctly, and that it is a supported
32+
version, open a command prompt and do:
33+
34+
python --version
35+
36+
## Pip
37+
38+
We are going to be using pip, so make sure that you have it installed and that
39+
you have the latest version:
40+
41+
python -m ensurepip --upgrade
42+
43+
## Example Scripts
44+
45+
You probably want a copy of the example Python scripts from the ORE project.
46+
So point your browser at the git repo...
47+
48+
https://gitlab.acadiasoft.net/qs/oreswig
49+
50+
...and click on the download button. Download a zip file of the repo and
51+
uncompress it somewhere on your hard drive.
52+
53+
Back at the command prompt, cd into the directory containing the example
54+
scripts, e.g:
55+
56+
cd C:\path\to\OREAnalytics-SWIG\Python\Examples
57+
58+
## Virtual Environment
59+
60+
Create a virtual environment into which you will install the ORE Python library:
61+
62+
python -m venv env1
63+
64+
Activate the virtual environment:
65+
66+
.\env1\Scripts\activate.bat
67+
68+
You might get a warning message that the version of pip installed inside the
69+
virtual environment is out of date, and you can make that go away with:
70+
71+
python -m pip install --upgrade pip
72+
73+
Some of the example scripts depend on other Python libs, here is the command to
74+
install those prerequisites:
75+
76+
pip install jinja2 pandas
77+
78+
Now, after all that, you are finally ready to install ORE!
79+
80+
pip install open-source-risk-engine
81+
82+
Now you can run the example scripts, e.g:
83+
84+
python swap.py
85+
86+
Once you are done using your virtual environment, you can exit it using the
87+
following command:
88+
89+
deactivate
90+
91+
You can later re-enter the virtual environment with the same command that you
92+
used earlier:
93+
94+
.\env1\Scripts\activate.bat
95+
96+
To delete the virtual environment, simply deactivate it (if necessary) and then
97+
delete the relevant directory:
98+
99+
rmdir /s /q env1
100+

0 commit comments

Comments
 (0)