Skip to content

Commit 3699f7c

Browse files
TysonRayJonesTysonRayJones
authored
restructured and extended examples (#593)
- moved and renamed isolated examples - tidied example-related CMakeLists.txt - updated example-related doc - added dynamics example - updated min_example to be C/C++ agnostic - change compile workflow to run Windows first (since MSVC is the most pedantic compiler of those tested so should run and fail soonest)
1 parent 2b4623c commit 3699f7c

39 files changed

+566
-381
lines changed

‎.github/workflows/compile.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ jobs:
5353

5454
# compile QuEST with all combinations of below flags
5555
matrix:
56-
os: [ubuntu-latest, macos-latest, windows-latest]
56+
os: [windows-latest, ubuntu-latest, macos-latest]
5757
precision: [1, 2, 4]
5858
omp: [ON, OFF]
5959
mpi: [ON, OFF]

‎CMakeLists.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -428,7 +428,7 @@ add_subdirectory(quest)
428428
## Examples
429429

430430
add_executable(min_example
431-
examples/tutorials/min_example.cpp
431+
examples/tutorials/min_example.c
432432
)
433433
target_link_libraries(min_example PRIVATE QuEST::QuEST)
434434

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@ mkdir build
239239
cd build
240240
```
241241

242-
Compile the [minimum example](/examples/tutorials/min_example.cpp) using [cmake](https://cmake.org/):
242+
Compile the [minimum example](/examples/tutorials/min_example.c) using [cmake](https://cmake.org/):
243243
```bash
244244
cmake ..
245245
make

‎docs/cmake.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,4 +71,5 @@ make
7171
| `CMAKE_C_COMPILER` | The C compiler that will be used to compile QuEST. | [CMAKE_\<LANG\>_COMPILER](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html) |
7272
| `CMAKE_INSTALL_PREFIX` | The directory to which QuEST will be installed when `make install` is invoked. A standard GNU directory structure (lib, bin, include) will be used inside the prefix directory. | [CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) <br> [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) |
7373
| `CMAKE_CUDA_ARCHITECTURES` | Used to set the value of `arch` when compiling for NVIDIA GPU. This is also known as the target GPU's "compute capability" and can be discovered [here](https://developer.nvidia.com/cuda-gpus). | [CMAKE_CUDA_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_ARCHITECTURES.html) |
74-
| `CMAKE_HIP_ARCHITECTURES` | Used to set the HIP platform which QuEST is compiled for when compiling for AMD GPU. | [CMAKE_HIP_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_HIP_ARCHITECTURES.html) |
74+
| `CMAKE_HIP_ARCHITECTURES` | Used to set the HIP platform which QuEST is compiled for when compiling for AMD GPU. | [CMAKE_HIP_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_HIP_ARCHITECTURES.html) |
75+
| `CMAKE_RUNTIME_OUTPUT_DIRECTORY` | The output directory to which to save compiled executables, overriding the default `build` folder | [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`](https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html). |

‎docs/compile.md

Lines changed: 72 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Compiling is configured with variables supplied by the [`-D` flag](https://cmake
3030
> - <a href="#compile_optimising">Optimising</a>
3131
> - <a href="#compile_linking">Linking</a>
3232
> - <a href="#compile_configuring">Configuring</a>
33+
> * <a href="#compile_location">Location</a>
3334
> * <a href="#compile_precision">Precision</a>
3435
> * <a href="#compile_compilers">Compilers</a>
3536
> * <a href="#compile_flags">Flags</a>
@@ -86,7 +87,7 @@ cmake --build .
8687
> cmake --build . --parallel
8788
> ```
8889
89-
With no additional arguments, these commands compile [`min_example.cpp`](/examples/tutorials/min_example.cpp) into an executable `min_example` in the `build` folder which can be run via
90+
With no additional arguments, these commands compile [`min_example.c`](/examples/tutorials/min_example.c) into an executable `min_example` in the `build` folder which can be run via
9091
```bash
9192
./min_example
9293
```
@@ -188,6 +189,11 @@ where
188189
- `myfile.c` is your `C` source file (or `myfile.cpp` if using `C++`).
189190
- `myexec` is the output executable name, which will be saved in `build`.
190191
192+
193+
> [!IMPORTANT]
194+
> `USER_SOURCE` can be any relative or absolute path to a file, but `OUTPUT_EXE` must be strictly a filename and cannot contain subdirectories. See <a href="#compile_location">Location</a> to change the output directory.
195+
196+
191197
To compile multiple dependent files, such as
192198
```cpp
193199
/* myfile.cpp */
@@ -241,6 +247,60 @@ to your project as a library!
241247
## Configuring
242248
243249
250+
251+
<!-- permit doxygen to reference section -->
252+
<a id="compile_location"></a>
253+
254+
### Location
255+
256+
The location of your compiled executable(s) can be changed (from the default `build`) using [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`](https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html).
257+
For example
258+
```bash
259+
# configure
260+
cmake .. -D CMAKE_RUNTIME_OUTPUT_DIRECTORY=/full/path/to/output/dir/
261+
```
262+
263+
This applies to _all_ built executables, including your own custom files, the examples, and the unit tests. All executables will be at the top-level of the specified directory, and will _not_ be contained with subdirectories like `/examples/`.
264+
265+
> [!TIP]
266+
> Paths containing spaces can be individually escaped, or the path surrounded with quotations, i.e.
267+
> ```bash
268+
> cmake .. -D CMAKE_RUNTIME_OUTPUT_DIRECTORY="/full/path/to/output/dir/"
269+
> ```
270+
> Beware that syntax like `~` will not be expanded inside quotation marks, but one can safely use alternative methods like
271+
> ```bash
272+
> "$HOME/path/from/home/to/output/dir/"
273+
> "../../path/from/two/layers/above/to/output/dir/"
274+
> ```
275+
276+
> [!NOTE]
277+
> Building will fail if the linker has insufficient permissions to make a new directory, for example with message:
278+
> ```bash
279+
> ld: open() failed, errno=2
280+
> ```
281+
> This is remedied by ensuring the output directory already exists.
282+
> ```bash
283+
> # make directory
284+
> export OUT_DIR=/full/path/to/output/dir/
285+
> mkdir $OUT_DIR
286+
>
287+
> # configure
288+
> cmake .. -D CMAKE_RUNTIME_OUTPUT_DIRECTORY=$OUT_DIR
289+
>
290+
> # build
291+
> cmake --build .
292+
> ```
293+
294+
> [!IMPORTANT]
295+
> Configuration will fail if any two executables have the same output name since they will not be separated into subdirectories and will collide. We do not gaurantee that all test and example filenames will remain unique in the future, such that use of `CMAKE_RUNTIME_OUTPUT_DIRECTORY` may become invalid except when also specifying
296+
> ```
297+
> -D ENABLE_TESTING=OFF -D BUILD_EXAMPLES=OFF
298+
> ```
299+
300+
301+
302+
303+
244304
<!-- permit doxygen to reference section -->
245305
<a id="compile_precision"></a>
246306
@@ -335,13 +395,21 @@ cmake .. -D BUILD_EXAMPLES=ON
335395
# build
336396
cmake --build .
337397
```
338-
The executables will be saved in the (current) `build` directory, in a sub-directory structure mimicking the [`examples/`](/examples/) folder. They can be run by e.g.
398+
Unless overridden with [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`](https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html), the executables will be saved in the `build` directory, in a sub-directory structure mimicking that of the [`examples/`](/examples/) folder. They can be run by e.g.
339399
```bash
340-
./examples/matrices/cpp_initialisation
400+
./examples/isolated/initialising_paulis_c
341401
```
342-
as elaborated upon in [`launch.md`](launch.md#tests).
402+
as elaborated upon in [`launch.md`](launch.md#examples).
343403
<!-- @todo the above link fails in Doxygen; it's too stupid to recognise the section ref -->
344404

405+
> [!NOTE]
406+
> <!-- @todo the below link fails in Doxygen; it's too stupid to recognise the section ref -->
407+
> As [above](compile.md#compile_optimising), Windows users should specify additional build parameter `--config Release` which will cause the executables to be contained in an additional final `\Release\` subdirectory. Executables are also suffixed with `.exe`, e.g.
408+
> ```
409+
> \examples\isolated\Release\initialising_paulis_c.exe
410+
> ```
411+
412+
345413
346414
347415
------------------

‎docs/launch.md

Lines changed: 47 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -59,41 +59,57 @@ Launching your [compiled](compile.md) QuEST application can be as straightforwar
5959
> See [`compile.md`](compile.md#examples) for instructions on compiling the examples.
6060
<!-- @todo the above link fails in Doxygen; it's too stupid to recognise the section ref -->
6161
62-
The example source codes are located in [`examples/`](/examples/) and are divided into subdirectories, e.g.
62+
63+
The example source codes are located in [`examples/`](/examples/) with structure
6364
```
6465
examples/
65-
krausmaps/
66-
initialisation.c
67-
initialisation.cpp
68-
reporters/
69-
env.c
70-
env.cpp
71-
matrices.c
72-
matrices.cpp
73-
...
74-
```
75-
where `file.c` and `file.cpp` respectively demonstrate QuEST's `C11` and `C++14` interfaces.
76-
These files are [compiled](compile.md#examples) into executables of the same name, respectively prefixed with `c_` or `cpp_`, and saved in subdirectories of `build` which mimic the structure of `examples/`. E.g.
66+
isolated/
67+
complex_arithmetic.c
68+
complex_arithmetic.cpp
69+
...
70+
extended/
71+
dynamics.c
72+
dynamics.cpp
73+
...
74+
tutorials/
75+
min_example.c
76+
...
77+
```
78+
where `file.c` and `file.cpp` respectively demo QuEST's `C11` and `C++14` interfaces. Files are divided between subdirectories:
79+
- `isolated/` which contains demos of _one_ function or task, typically showcasing all the different syntaxes and interfaces available.
80+
- `extended/` which contains longer, standalone examples performing common tasks and algorithms in quantum computing.
81+
- `tutorials/` which contains guides with step-by-step explanations.
82+
83+
84+
These files are [compiled](compile.md#examples) into executables of the same name, respectively suffixed with `_c` or `_cpp`, and (by default) are saved in subdirectories of `build` which mimic the structure of `examples/`. E.g.
85+
<!-- @todo the above link fails in Doxygen; it's too stupid to recognise the section ref -->
7786
```
7887
build/
7988
examples/
80-
krausmaps/
81-
c_initialisation
82-
cpp_initialisation
83-
reporters/
84-
c_env
85-
cpp_env
86-
c_matrices
87-
cpp_matrices
88-
...
89-
```
89+
isolated/
90+
complex_arithmetic_c
91+
complex_arithmetic_cpp
92+
...
93+
extended/
94+
dynamics_c
95+
dynamics_cpp
96+
...
97+
tutorials/
98+
min_example_c
99+
```
100+
101+
> [!NOTE]
102+
> <!-- @todo the below link fails in Doxygen; it's too stupid to recognise the section ref -->
103+
> On Windows, the executables are located in `\Release\` subdirectories, assuming the parameter
104+
> `--config Release` was specified during compilation (see [compiled](compile.md#compile_optimising)).
105+
90106
Most of these executables can be run directly from within `build`, e.g.
91107
```bash
92-
./examples/reporters/cpp_paulis
108+
./examples/extended/dynamics_c
93109
```
94110
while others require command-line arguments:
95111
```bash
96-
./examples/reporters/c_env
112+
./examples/extended/reporting_environments_cpp
97113

98114
# output
99115
Must pass single cmd-line argument:
@@ -105,6 +121,12 @@ Must pass single cmd-line argument:
105121
6 = auto
106122
```
107123

124+
> [!NOTE]
125+
> On Windows, the executables are `.exe` files and can be run with e.g.
126+
> ```
127+
> \examples\isolated\Release\initialising_paulis_c.exe
128+
> ```
129+
108130
109131
---------------------
110132

‎examples/CMakeLists.txt

Lines changed: 59 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,61 @@
11
# @author Oliver Thomson Brown
2+
# @author Erich Essmann (updating rpath)
3+
# @author Tyson Jones (refactored to functions + glob)
24

3-
add_subdirectory(krausmaps)
4-
add_subdirectory(matrices)
5-
add_subdirectory(numbers)
6-
add_subdirectory(paulis)
7-
add_subdirectory(reporters)
8-
add_subdirectory(superoperators)
9-
add_subdirectory(debug)
5+
6+
7+
# compiles in_fn to ../examples/direc/in_fn_c
8+
9+
function(add_example direc in_fn)
10+
11+
# fn.cpp -> filename=fn, filelang=cpp
12+
get_filename_component(filename ${in_fn} NAME_WE)
13+
get_filename_component(filelang ${in_fn} LAST_EXT)
14+
string(REPLACE "." "" filelang ${filelang})
15+
16+
set(target "${filename}_${filelang}")
17+
set(out_fn "${filename}_${filelang}")
18+
set(out_dir "${CMAKE_INSTALL_BINDIR}/examples/${direc}/")
19+
20+
add_executable(${target} ${in_fn})
21+
target_link_libraries(${target} PUBLIC QuEST)
22+
23+
install(
24+
TARGETS ${target}
25+
RUNTIME
26+
DESTINATION ${out_dir}
27+
)
28+
29+
set_target_properties(${target}
30+
PROPERTIES
31+
INSTALL_RPATH "${CMAKE_INSTALL_FULL_LIBDIR}"
32+
OUTPUT_NAME "${out_fn}"
33+
)
34+
35+
endfunction()
36+
37+
38+
39+
# compiles all .c or .cpp files in the subdirecs below
40+
41+
function(add_all_local_examples)
42+
43+
get_filename_component(direc ${CMAKE_CURRENT_LIST_DIR} NAME)
44+
45+
file(GLOB files
46+
"${CMAKE_CURRENT_SOURCE_DIR}/*.c"
47+
"${CMAKE_CURRENT_SOURCE_DIR}/*.cpp"
48+
)
49+
50+
foreach(fn ${files})
51+
add_example(${direc} ${fn})
52+
endforeach()
53+
54+
endfunction()
55+
56+
57+
58+
# all subdirecs below will invoke add_all_local_examples()
59+
60+
add_subdirectory(isolated)
61+
add_subdirectory(extended)

‎examples/debug/CMakeLists.txt

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎examples/extended/CMakeLists.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# @author Tyson Jones
2+
3+
add_all_local_examples()

0 commit comments

Comments
 (0)