Category Archives: Julia

Local test coverage in Julia

By: Tamás K. Papp

Re-posted from: https://tamaspapp.eu/post/julia-local-coverage/

While codecov.io and coveralls.io are fine services and very easy to set up for Github repositories with Julia packages, they become more difficult to use under some circumstances. For example, if testing requires large binaries you don’t want to build every time, you need to build a Docker image to run testing and obtain coverage information. Also, if your test scripts take a long time and you have access to a powerful computer, you might want to just run coverage locally when working on the code.

Naturally, Julia has all the facilities for generating and collecting coverage information locally. To make their application even easier, I packaged up a small set of scripts in LocalCoverage.jl that I use to generate and visualize coverage information for Julia packages on my machine.

This is how it works:

  1. run generate_coverage(pkg) to

    a. run Pkg.test(pkg; coverage = true),

    b. use Coverage.jl for collecting information to a single file in lcov format,

    c. unless disabled, run the external program genhtml to format everything as a nice HTML file.

  2. if you have generated the HTML files, open_coverage(pkg) opens them for you in your default browser.

  3. if you want to tidy up, run clean_coverage(pkg).

This is what it looks like for this package:

Setting up Julia with continuous integration on Gitlab

By: Tamás K. Papp

Re-posted from: https://tamaspapp.eu/post/julia-ci-gitlab/

As an academic, I picked up good practices for programming mostly by osmosis. My approach to “testing” software went through the following stages:

  1. See if the code runs (this got me through my undergrad years).

  2. Check if the results “look OK”, then forget about testing.

  3. Compare results occasionally to known results from papers or other code (eg in a different language).

  4. Write some unit tests ex post, as an afterthought after the code is finished (time pressure helps to ensure that overtesting is never a problem).

  5. Use unit tests from the very beginning, especially before optimizing and refactoring code.

  6. Set up automatic testing, as part of continuous integration.

I think that 1–3 above is a pretty usual path, naturally traversed after the recognition that some testing would be nice, but lacking the knowledge of how to implement it in a consistent manner. This is comparable to using copies of directories as crude attempts at “version control”.

Later, I picked up 4–6 while being exposed to these ideas when learning about new languages. Automated unit testing is one of those things one does not miss until learning about it, then subsequently cannot imagine doing without. In a research context, the two main advantages are scientific integrity — I should make a best effort to ensure that my results are correct — and dealing with bugs early. While the first one is abstract and philosophical, the second is a practical concern: I found that if I skimp on testing, the bugs show up much later, usually at an inconvenient time, and I will have to spent time locating the bug (not always trivial, especially with numerical code) and switch context to something I was working on months ago. It is my experience that while tests can be tedious to write, time spent on them is a very good investment.

I knew about unit tests before coming to Julia, but learned about automated CI in the Julia community. This was because package template libraries “do the right thing” by making it very easy to set up an automated testing framework: for example, PkgDev.generate creates the appropriate test configuration for Travis CI and various coverage services.

I never cease to be amazed by the fact that these services are available for free for public / open source projects, which is very generous of these providers. However, occasionally one would like to keep the project private for a little while. The usual scenario for me is working on code that is related to a paper, which I plan to make public with the latter; in this case one would need the pro (non-free) version of Travis and related tools.

Alternatively, Gitlab offers CI/CD with private repositories. I am exploring this at the moment for various projects, and boiled down the necessary configuration into the repository GitlabJuliaDemo.jl. It has

  1. a CI setup for Pkg.test,

  2. a coverage summary as a percentage.

While coverage analysis could be automated too with a custom Docker image, I leave his for future work.1

So far, I am very satisfied with Gitlab. The interface is well-designed, clean, and intuitive; tests complete in a few minutes (just like Travis).


  1. In the next post I will talk about local coverage analysis in Julia. [return]

Julia with Emacs Org mode

By: Picaud Vincent

Re-posted from: https://pixorblog.wordpress.com/2018/03/07/julia-with-emacs-org-mode/

Introduction

This post details how to use Emacs Org mode to create Julia notebooks and to perform HTML or PDF exports. I tried to get the simplest working solution.

Julia notebook functionality works out of the box thanks to ob-julia.el and this is what I am using instead of Jupiter notebooks. However, the solution to export HTML and PDF is not straightforward.

I wanted to:

  • have nice Julia code snippets with full UTF8 supports,
  • being able to export in both HTML and PDF, including bibliography.

I get a solution which is certainly not perfect, ideas to improve it are welcomed.

There are two points to take care of:

  • LaTeX does not fully support UTF8, nor its listings package.
    • for UTF8 support I had to switch to luatex, biber and minted package
    • I also had to use proper fonts, DejaVu, to support Greek letters and mathematical symbols.
  • to make the bibliography exportable in both HTML and PDF without .org file modification, I had to use a little trick.

The proposed solution uses:

  • ob-julia.el : to support notebook functionality,
  • ox-bibtex.el : used for html-export of the bibliography, requires bibtex2html (Debian package),
  • luatex : under Debian, included in the texlive-latex-base package,
  • biber : under Debian, the biber package,
  • pygments : under Debian, the python-pygments package. Attention with python3-pygments, it does not on my computer. I have not investigated this.

Maybe I have forgotten something, just tell me (I am only using Linux).

There is a GitHub repository to reproduce results of this post. The example.pdf generated file is also present.

Emacs configuration

Getting ob-julia.el and ox-bibtex.el

You can found ob-julia.el and ox-bibtex.el in Org-mode Contributed Packages. Easy download can be performed using:

curl -o emacs_files/ob-julia.el https://code.orgmode.org/bzg/org-mode/raw/master/contrib/lisp/ob-julia.el
curl -o emacs_files/ox-bibtex.el https://code.orgmode.org/bzg/org-mode/raw/master/contrib/lisp/ox-bibtex.el

Minimal init.el file

This is a minimal configuration to reproduce the results. The code with its comments is self-explaining:

;; Use your own packages for classical stuff
(package-initialize)
;; requires Emacs speaks statistics, Org
(require 'ess-site)
(require 'org)

;; removes ugly horizontal lines in html-exported code 
;; (not mandatory)
(setq org-html-keep-old-src t)

;; As ob-julia.el and ox-bibtex are less common, 
;; we use a local repository.
;;
;; Usage: emacs -q --load emacs_files/init.el
;;
;; In a more usual setting one should use:
;; (require 'ob-julia.el)
;; (require 'ox-bibtex)
(load-file "emacs_files/ob-julia.el") ; works with ess-site, our notebook engine
(load-file "emacs_files/ox-bibtex.el"); used for bibliography HTML-export 

;; allows julia src block (requires ob-julia.el)
(setq org-confirm-babel-evaluate nil)

(org-babel-do-load-languages
 'org-babel-load-languages
 '((julia . t)))

;; defines image width in the OrgMode buffer (this is not for html
;; exports, for this you must use #+HTML_ATTR: :width 900px for
;; instance)
;;
;; This is not mandatory, but useful when one uses the gr() Plots.jl
;; backend as it exports wide .png files. CAVEAT: use imagemagick for
;; image resizing.
;;
(setq org-image-actual-width (/ (display-pixel-width) 4))

;; uses the minted package instead of the listings one
(setq org-latex-listings 'minted)

;; defines how to generate the pdf file using lualatex + biber
(setq org-latex-pdf-process
      '("lualatex -shell-escape -interaction nonstopmode -output-directory %o %f"
        "biber %b"
        "lualatex -shell-escape -interaction nonstopmode -output-directory %o %f"
        "lualatex -shell-escape -interaction nonstopmode -output-directory %o %f"))

.org file configuration

For demonstration purpose we define an .org file example. This file is kept very simple to do not distract from the required configuration part.

LaTeX directives

We have the LaTeX configuration part:

# uses minted package instead of listings 
#+LATEX_HEADER: \usepackage{minted}    

# uses fonts to support Greek letters etc...
#+LATEX_HEADER: \usepackage{fontspec}
#+LATEX_HEADER: \setmonofont{DejaVu Sans Mono}[Scale=MatchLowercase]

# defines the \begin{comment} \end{comment} environment, used to avoid
# conflict between bibtex and biblatex
#+LATEX_HEADER: \usepackage{verbatim} 

# uses the biblatex package (and not the old bibtex) 
#+LATEX_HEADER: \usepackage[backend=biber, bibencoding=utf8 ]{biblatex}
# our bibliography file
#+LATEX_HEADER: \addbibresource{my-bib.bib}

We then define our the Julia code highlight style. This style is used by minted for PDF export.

#+BEGIN_EXPORT latex
\definecolor{bg}{rgb}{0.95,0.95,0.95}
\setminted[julia]{
  bgcolor=bg,
  breaklines=true,
  mathescape,
  fontsize=\footnotesize}
#+END_EXPORT

Our notebook

Now this is the beginning of our notebook. One can use Org as usual…

#+TITLE: My title
#+AUTHOR: author

* Very simple demo

#+BEGIN_SRC julia  :eval no-export :session *demo_session* :exports none
using Plots
#+END_SRC 

** UTF8 support + escape math equation
Note that UTF8 is supported (the \alpha variable) :

#+BEGIN_SRC julia :eval no-export :session *demo_session* :exports both :results silent :wrap "SRC julia :eval never"
# Generate a matrix $a_{i,j}=\mathcal{U}([0,1[)$
α=rand(4,5)
#+END_SRC

** Long lines are wrapped

#+BEGIN_SRC julia :eval no-export :session *demo_session* :exports both :results output :wrap "SRC julia :eval never"
function ⊗(a::AbstractArray{T},b::AbstractArray{S}) where {T<:Number,S<:Number} kron(a,b) end;

β=rand(2,5);
γ = α ⊗ β
#+END_SRC

** Plot example

You can easily generate plots, one example from [[http://docs.juliaplots.org/latest/examples/pyplot/][Plots Julia package]],
 is used to generate Figure [[PolarPlot]].

#+BEGIN_SRC julia  :eval no-export :session *demo_session* :exports code :results silent
Θ = linspace(0,1.5π,100)
r = abs(0.1 * randn(100) + sin.(3Θ))
plot(Θ,r,proj=:polar,m=2)
#+END_SRC

#+BEGIN_SRC julia  :eval no-export :session *demo_session* :results graphics :file example.png :exports results
savefig("example.png")
#+END_SRC

#+CAPTION: A polar plot.
#+ATTR_HTML: :width 900px
#+NAME: PolarPlot
#+RESULTS:
[[file:example.png]]

** Org with bibliography

\begin{align}
\label{eq:one_eq}
{\frac {d}{dt}}\iint _{\Sigma (t)}\mathbf {F} (\mathbf {r} ,t)\cdot d\mathbf {A} = & \iint _{\Sigma (t)}\left(\mathbf {F} _{t}(\mathbf {r},t)+\left[\nabla \cdot \mathbf {F} (\mathbf {r} ,t)\right]\mathbf {v}
\right)\cdot d\mathbf {A} - \\
& \oint _{\partial \Sigma (t)}\left[\mathbf{v} \times \mathbf {F} (\mathbf {r} ,t)\right]\cdot d\mathbf {s} \nonumber
\end{align}

Eq. \ref{eq:one_eq} is demonstrated in cite:Flanders1973.

Bibliography

Now we reach a little trick to support both HTML and PDF bibliography exports:

#+BEGIN_EXPORT latex
\printbibliography
#+END_EXPORT

#+BEGIN_EXPORT latex
\begin{comment}
#+END_EXPORT
#+BIBLIOGRAPHY: my-bib plain
#+BEGIN_EXPORT latex
\end{comment}
#+END_EXPORT

Explanation:

To export HTML bibliography, ox-bibtex does the job with only one directive:

#+BIBLIOGRAPHY: my-bib plain

However, for PDF export we do not want to use ox-bibtex, as it does not support UTF8. The solution is to wrap this directive into a comment section in the generated .tex code:

#+BEGIN_EXPORT latex
\begin{comment}
#+END_EXPORT
#+BIBLIOGRAPHY: my-bib plain
#+BEGIN_EXPORT latex
\end{comment}
#+END_EXPORT

Now we must tell LaTeX to use biblatex, this is done thanks to this directive:

#+BEGIN_EXPORT latex
\printbibliography
#+END_EXPORT

Putting everything together you get the proposed solution. This is certainly not the cleanest approach, but I have not found simpler.

The my-bib.bib file

For our example we need a small bibliography my-bib.bib file:

@article{Flanders1973,
  doi = {10.2307/2319163},
  url = {https://doi.org/10.2307/2319163},
  year  = {1973},
  month = {jun},
  publisher = {{JSTOR}},
  volume = {80},
  number = {6},
  pages = {615},
  author = {Harley Flanders},
  title = {Differentiation Under the Integral Sign},
  journal = {The American Mathematical Monthly}
}

Usage

You can visit the GitHub repo to reproduce the results.

Starting Emacs with the local configuration

From project root directory type

emacs -q --load emacs_files/init.el

to start a new Emacs with our local configuration.

Recomputing the notebook

As I potentially have several notebooks to publish I have used the :eval no-export argument. By consequence the notebooks are not evaluated each time you publish but only once. If you want to recompute everything every time, simply remove this option. You can also use the :cache option.

By consequence, before exporting you must begin by a first evaluation of the notebook. Visit the example.org buffer and do M-x org-babel-execute-buffer (or use the C-c C-v b shortcut). Attention, be sure that Plots.jl is installed.

ERROR: MethodError: no method matching start(::…)

In the ∗demo_session∗ Julia session buffer you will certainly see this error:

ERROR: MethodError: no method matching start(::...)

This is not our fault, but a known problem (that would need a fix) julia-print-commands-not-working-in-emacs-org-mode. It does not affect the computed result (but only the output processing). To get the right output (without the error message) one workaround is to restart computation of the source block (C-c C-c).

Exporting

Still from the example.org buffer, you can do:

  • HTML export with: C-c C-e h o
  • PDF export with: C-c C-e l o

This should generate and open fresh hmtl and pdf files.

Note: concerning html files, this is a basic export, you can use your own HTML theme.