--help
This section will describe the main softwares I rely upon for my work and give a few indication on how to use them
Markdown
Markdown is a formatting language created by John Gruber and Aaron Swartz in 2004 as an easy to write and use formatting option. Where HTML or Latex need explicit tags to indicate the formatting (such as <strong></strong> or \textbf{} for bold text), Markdown uses minimalist indicators (** around bold text).
That way, the markdown text is still very readable even without being rendered as a webpage or PDF.
In particular, many modern text editors offer syntax highlighting for markdown files, allowing an easy editing of documents.
Markdown files have an extension .md or .mdown and MIME type text/markdown.
Note
Variants of markdown exist, such as the git-flavored markdown (gfm) used on git repository pages. Variant include specific style and methods such as citations, task list, …
Tools such as Pandoc can be used to convert markdown files into latex, PDF or word documents for larger distributions.
Tip
Visit https://www.markdownguide.org/ for a full documentation of markdown format.
reStructure Text
Another minimal markup language is reStructure Text. It is very similar to Markdown, but includes additional commands (called directives) to structure the document (such as include). Closer to Latex than Markdown, it is more adapted to the production of large documents, inclusion of images, …
reStructure Text files have an extension .rst and MIME type text/x-rst.
Tip
Visit https://docutils.sourceforge.io/rst.html for a full documentation of reStructure Text format
Note
The current document is written in reStructure Text.
Pandoc
Pandoc is a universal document converter. It translates documents from Markdown, Latex, … to other formats (either ligth markup style, or heavier ones such as MS Word or HTML).
In particular, it can translate from Markdown to Latex and from there be compiled into a PDF file (a PDF file can also be obtained via the Markdown \(\rightarrow\) Word \(\rightarrow\) PDF path).
Pandoc includes modules to process math equations and citations.
Typical Pandoc call looks like :
$ pandoc --standalone --table-of-contents \
--biblatex \
--to=latex --output=output.tex \
--from=gfm input.md
Tip
Visit https://pandoc.org/ for a full documentation on pandoc.
Sphinx
Like pandoc, Sphinx converts Markdown and reStructure Text documents into rendered documents like HTML pages or PDF using Latex.
Tip
Visit https://www.sphinx-doc.org for a full documentation on Sphinx.
Sphinx configuration
Producing this document uses Sphinx in conjunction with specific extensions (in particular for styling).
The sphinx configuration can be found in the conf.py file.
The extensions and environment to run sphinx and produce this document from source is available via the dedicated Dockerfile on git.unistra.fr.
Mermaid
Mermaid is a javascript packages that creates diagrams from definition using a simple syntax. The syntax can also be used in more general context to take notes, …
Note
Flow charts in the Implementation section are made with Mermaid.
Tip
Visit https://mermaid-js.github.io/mermaid/ for documentation, and https://mermaid.live/ for live trying Mermaid.
Yaml
Yaml (stands for Yaml Ain’t Markup Language) is a meta data language. It’s goal is to represent organized information (i.e. programming variables) in a human friendly way.
Yaml documents can be converted in to Json, XML, or Python’s dictionaries, …
A typical YAML document looks like this:
FC_DOF:
U3O8: 27.3981
UF4: 27.285
u_FC_DOF:
U3O8: 0.005
UF4: 0.005
SPEED_OF_LIGHT: 0.299792458 # meters per nanoseconds
TNT_TS_STEP: 10. # nanoseconds per timestamp
and will translate into the following json structure:
{
"FC_DOF": {
"U3O8": 27.3981,
"UF4": 27.285
},
"u_FC_DOF": {
"U3O8": 0.005,
"UF4": 0.005
},
"SPEED_OF_LIGHT": 0.299792458,
"TNT_TS_STEP": 10
}
Yaml files are easy to read directly in a text editor and can be imported into a software, which makes them particularly useful to store software configurations.
Yaml files have an extension .yml or .yaml and MIME type application/yaml.
In the context of Open Science, Yaml is also a great language to write metadata .
Tip
Visit https://yaml.org/ for a full documentation of the yaml format.
git
git is version control system designed for tracking changes in source code during software development.
It is very widely used in managing projects, and can be adapted to small or large teams, big or tiny projects.
The main feature of git is keeping a complete history of the project, including all changes made to the code.
The user can then create a flagged version of their files at any point in time, making it easier to go back to a previous version if (when) mistakes are made.
In addition, online services such as github, or gitlab instances provide remote servers on which to send and store the git repository, making it easier to share and keeping it for later use.
Tip
Visit https://git-scm.com/ for documentation on git. A good way to learn the versioning system is also to refer to the software carpentry class on the topic .
Note
The current manuscript sources, public pages, scripts, as well as supporting softwares have been written using git for version control as well as progress saving.
Their public versions are published and hosted on the Université de Strasbourg gitlab instance: https://git.unistra.fr/hdr-ghenning
Python
Python is a high-level, interpreted programming language known for its simplicity and readability. Created by Guido van Rossum in 1991, it has since become one of the most popular programming languages worldwide, used in domains such as web development, data analysis, artificial intelligence, scientific computing, and more.
Key features of Python include its clear and concise syntax, which emphasizes readability and reduces the cost of program maintenance. Python uses indentation to denote blocks of code, promoting code consistency and readability among developers.
Python files have an extension .py and MIME type application/x-python-code or text/x-python.
Tip
Visit https://www.python.org/ for all things related to Python.
Python comes with an extensive standard library, providing a wide range of extra packages to perform specific tasks such as database access, data manipulation, … Additionally, third-party libraries can easily be installed to further extends the language’s capabilities with libraries like NumPy, Pandas, Matplotlib and many others.
As an interpreted language, it suffers from slow execution time (compared to C++ for example) and high memory usage. However, these drawbacks are balanced by the high portability of the code that can be executed without any modification on Linux, Windows or MacOs plateform.
Danger
Although still in use for many projects, version 2.7 of python is now deprecated. And should not be used.
Python gave us the Zen of python that are fantastic guiding principle for programming.
pip
pip is a python tool to install external modules (modules are libraries one can load and used to extend python’s ability).
It takes care of modules’ dependencies and versions.
It is recommended to publish python modules on the Pypi website so that they can be installed by the simple command :
$ pip install `module-name`
Tip
Visit https://pip.pypa.io/ for the pip documentation and https://pypi.org/ to browse the available modules.
Note
My own published modules can be found on https://pypi.org/user/ghenning/ .
Virtual environment
A virtual environment in Python is a directory that contains a specific reference to the Python interpreter, and, more importantly, a set of installed packages.
It makes it possible to have an isolated environment for Python projects, ensuring that dependencies are managed separately and avoiding conflicts between different projects that may share the same name, or require different versions of the same package. The packages loaded into a virtual environment are usually limited in number, it makes the dependency management easier than on a system-wide installation where many unrelated packages may be installed.
Virtual environments also allow developers to replicate a specific environment in which to develop and test the code in different computers and between different collaborators.
There are different ways to create virtual environments, depending on the version of python installed and general framework used. For example conda provides package dependence and environment management on a very detail level, but comes with a large codebase (it is a framework that encapsulates python within an extended environment). The virtualenv tool is closer to the bare python, managing not only packages but also python version within the virtual environment.
The simplest solution, and the one I personally prefer because it does not require additional packages, is the built-in venv module from the python standard library.
Even with limited capabilities compared to more advanced solutions, it is always available and does the job.
Jupyter notebooks
Jupyter notebooks, as well as the Jupyter-lab environment is a full python IDE that runs as a server and can be accessed via the web-browser.
This offer several advantages: first, the server can run on a specific machine (for example, at the in2p3 computation center) and be accessed from a desktop or laptop. Second, the using tabs, one can easily organize the workspace and switch between files, terminals and file display.
The Notebooks, especially, mix computing cells (containing for example Python code) with rendered Markdown text. The final document is therefore directly readable and shows the full process of analysis directly.
Notebooks files are formerly json files, with an extension .ipynb and MIME type application/x-ipynb+json.
Note
Most of the development of the data analysis in this manuscript has been done within a jupyter-lab environment.
Tip
Visit https://jupyter.org/ to discover Jupyter and Jupyter Lab.
Emacs
Emacs is an historical text editor for Linux. Now available on all platforms. It runs either in the terminal or with a GTK visual interface. It provides syntax highlighting for many languages (including Python, Markdown, Yaml, …)
Emacs uses many keyboard combination shortcuts to find, modify, save, … and once the mains ones are remembered, it can be a very powerful tool for programming. The Emacs’ keybindings are so specific and well known by their users that they are a frequent possible setting in IDEs.
Emacs archenemy is vim, with its own keyboard shortcuts. The Emacs vs. Vim conflict has been raging for years, with no signs of ever ending [1].
Tip
Visit https://www.gnu.org/software/emacs/ to get Emacs.
Visual Studio code
Visual Studio Code (also known as VS Code) is a modern source code editor by Microsoft (launched in 2015). Although a Microsoft product, it has been developed on other platforms and can be run on Windows, macOS, and Linux, as well as online (when connected to a github account for example) providing a consistent development experience across different operating systems.
It is a highly customizable IDE, supporting syntax highlighting for an extensive list of programming languages. It can also load extensions that augment its capabilities. For example, one can preview Markdown or reStructure Text documents, open and run jupyter notebooks, perform git operations, … from within VS Code. The shortcuts can also be redefined, to fit, for example, the Emacs key bindings.
Note
This manuscript has been written within VS code.
Tip
Visit https://code.visualstudio.com/ to see how you can get VS Code on your computer.
Docker
Docker is a containerization platform that allows users to package applications and their dependencies into isolated environments called containers. These containers can run on any operating system without modification, providing consistency across different environments.
This solution ensures the consistency of an environment for research projects and softwares (See more about that in the Open Source section and [2]). T he Docker image packages the relevant code along with all necessary dependencies, ensuring that the software will run in a consistent way regardless of where it is executed.
Furthermore, Docker images can be exported and shared, making it easier to share the content.
Along with Docker, other containerization softwares exists, such as Singularity/Apptainer or Podman, among many others.
Note
The Sphinx environnement (version, extension, …) used to compile the reStructure sources files into HTML and PDF is contained in a docker image.
On Windows systems, Docker uses the Windows Subsystem for Linux to run the containers.
Tip
Visit https://www.docker.com/ to install Docker and https://hub.docker.com/ to browse the library of publicly available images.
Talys
Talys is a nuclear reaction code for the prediction of reaction cross sections and related quantities [3]. It can handle reactions induced by neutrons, photons, protons, deuterons, and other light ions, on target nuclei from mass 12 to the heaviest tabulated isotopes, and for incident energies from the eV to hundreds of MeV range.
For the beginner, Talys can be used with minimal inputs.
Indeed, it just needs four keywords to run properly: the projectile and its energy, and the mass of the target element.
However, for more detailed works, the number of keywords that allow the Talys calculation to be tweaked is huge.
An isotope level scheme can be changed, one level or one transitions at a time.
Isomer life time can be modified. Closer to the theoretical modelling, the level density, optical model potential, fission barrier, preequilibrium, and so on, parameters can be changed.
The output of Talys can also be extensive: cross section for many different output channels including partial transitions or level production.
Note
Since version 2.0, Talys can be tried live, online.
Tip
Visit https://nds.iaea.org/talys/ to download and install Talys.
Footnotes