Mercurial > repos > public > sbplib_julia

annotate README.md @ 1892:b00eb94848ba v0.1.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bump version to 0.1.4
author Jonatan Werpers <jonatan@werpers.com>
date Fri, 31 Jan 2025 10:47:14 +0100
parents 654a2b7e6824
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1726
471a948cd2b2 Rename project from Sbplib to Diffinitive
Vidar Stiernström <vidar.stiernstrom@gmail.com>
parents: 1302
diff changeset
1 # Diffinitive
349
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
2
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
3 ## Running tests
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
4 To run all tests simply run
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
5 ```
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
6 (@v1.5) pkg> activate .
1726
471a948cd2b2 Rename project from Sbplib to Diffinitive
Vidar Stiernström <vidar.stiernstrom@gmail.com>
parents: 1302
diff changeset
7 (Diffinitive) pkg> test
349
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
8 ```
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
9
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
10 If you want to run tests from a specific file in `test/`, you can do
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
11 ```
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
12 julia> using Pkg
709
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
13 julia> Pkg.test(test_args=["[glob pattern]"])
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
14 ```
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
15 For example
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
16 ```
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
17 julia> Pkg.test(test_args=["SbpOperators/*"])
349
76aa1486124a Add some info about running tests in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 333
diff changeset
18 ```
709
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
19 to run all test in the `SbpOperators` folder, or
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
20 ```
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
21 julia> Pkg.test(test_args=["*/readoperators.jl"])
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
22 ```
48a61e085e60 Add function for selecting tests
Jonatan Werpers <jonatan@werpers.com>
parents: 349
diff changeset
23 to run only the tests in files named `readoperators.jl`.
717
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
24 Multiple filters are allowed and will cause files matching any of the provided
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
25 filters to be run. For example
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
26 ```
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
27 Pkg.test(test_args=["*/lazy_tensor_operations_test.jl", "Grids/*"])
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
28 ```
1c5600a711ae Allow multiple filters
Jonatan Werpers <jonatan@werpers.com>
parents: 715
diff changeset
29 will run any file named `lazy_tensor_operations_test.jl` and all the files in the `Grids` folder.
840
221ce98d2612 Add some instructions to the README
Jonatan Werpers <jonatan@werpers.com>
parents: 717
diff changeset
30
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
31 ## Running benchmarks
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
32 Benchmarks are defined in `benchmark/` and use the tools for benchmark suites
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
33 in BenchmarkTools.jl. The format is compatible with PkgBenchmark.jl which
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
34 helps with running the suite, comparing results and presenting the results in
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
35 a readable way. There are custom functions included for running the benchmarks
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
36 in this Mercurial repository.
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
37
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
38 `benchmark/` contains a julia environment with the necessary packages for
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
39 working with the benchmarks.
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
40
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
41 To run the benchmarks, either use `make` or run them manually from the REPL, as
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
42 explained further below.
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
43
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
44 Using `make` there are four targets for benchmarks
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
45 ```shell
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
46 make benchmark # Runs the suite for the current working directory
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
47 make benchmarkrev REV=rev # Runs the suite at the specified revision
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
48 make benchmarkcmp TARGET=target BASELINE=baseline # Compares two revisions
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
49 make cleanbenchmark # Cleans up benchmark tunings and results
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
50 ```
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
51 Here `rev`, `target` and `baseline` are any valid Mercurial revision
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
52 specifiers.
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
53
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
54 Alternatively, the benchmarks can be run from the REPL. To do this, first
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
55 activate the environment in `benchmark/` then include the file
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
56 `benchmark_utils.jl`. The suite can then be run using the function `main` in
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
57 one of the following ways
1194
007d90b354af More readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1193
diff changeset
58
007d90b354af More readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1193
diff changeset
59 ```julia
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
60 main() # Runs the suite for the current working directory
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
61 main(rev="...") # Runs the suite at the specified revision
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
62 main(target="...", baseline="...") # Compares two revisions
1194
007d90b354af More readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1193
diff changeset
63 ```
007d90b354af More readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1193
diff changeset
64
1378
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
65 Again, `rev`, `target` and `baseline` are any valid Mercurial revision
2b5480e2d4bf Fix some errors in README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 1302
diff changeset
66 specifiers.
1195
8a1de954bdf9 Even more readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1194
diff changeset
67
1196
2f208828ae58 Just a little bit more readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1195
diff changeset
68 PkgBenchmark can also be used directly.
2f208828ae58 Just a little bit more readme
Jonatan Werpers <jonatan@werpers.com>
parents: 1195
diff changeset
69
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
70 ```julia
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
71 using PkgBenchmark
1726
471a948cd2b2 Rename project from Sbplib to Diffinitive
Vidar Stiernström <vidar.stiernstrom@gmail.com>
parents: 1302
diff changeset
72 import Diffinitive
471a948cd2b2 Rename project from Sbplib to Diffinitive
Vidar Stiernström <vidar.stiernstrom@gmail.com>
parents: 1302
diff changeset
73 r = benchmarkpkg(Diffinitive)
1171
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
74
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
75 export_markdown(stdout, r)
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
76 ```
87bc91def1ff Start setting things up
Jonatan Werpers <jonatan@werpers.com>
parents: 847
diff changeset
77
847
0862bed6e6b4 Update README.md
Jonatan Werpers <jonatan@werpers.com>
parents: 846
diff changeset
78 ## Generating and using the documentation
840
221ce98d2612 Add some instructions to the README
Jonatan Werpers <jonatan@werpers.com>
parents: 717
diff changeset
79 Generating the documentation can be done using either `make` or through activating the `docs` environment and including the script `docs/make.jl` at the REPL.
221ce98d2612 Add some instructions to the README
Jonatan Werpers <jonatan@werpers.com>
parents: 717
diff changeset
80
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
81 Using `make` there are four targets for documentation
840
221ce98d2612 Add some instructions to the README
Jonatan Werpers <jonatan@werpers.com>
parents: 717
diff changeset
82 ```shell
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
83 make docs # generates files suitable for webserver deployment, i.e with `prettyurls=true`
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
84 make localdocs # generates files suitable for local viewing in a web browser, i.e `prettyurls=false`
1302
68dd0c9f5cac Add some notes
Jonatan Werpers <jonatan@werpers.com>
parents: 1284
diff changeset
85 make opendocs # build and view documentation locally
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
86 make cleandocs # cleans up generated files
846
c9e35f1ca269 Make the targets properly depend on the source files
Jonatan Werpers <jonatan@werpers.com>
parents: 842
diff changeset
87 ```
842
ef78f730cbb4 More info in the readme
Jonatan Werpers <jonatan@werpers.com>
parents: 840
diff changeset
88
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
89 Alternatively, to view the documentation locally simply open `docs/build/index.html` in your web browser. When including the `docs/make.jl` script `prettyurls` is set to `false` by default.
840
221ce98d2612 Add some instructions to the README
Jonatan Werpers <jonatan@werpers.com>
parents: 717
diff changeset
90
1284
f19c51ddbd72 Update readme with info about running benchmarks from make. Fix typos
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 1238
diff changeset
91 Including `docs/make.jl` from the REPL may be preferable when repeatedly building the documentation since this avoids compilation latency.