Adding a new Calculator

Introduction

In SimEx, a Calculator is a python class. It serves as an API (application-programming interface) to physics simulation codes. It's purpose is to provide a unified user experience to various simulation codes targeting the same or similar physics problems.

Using a Calculator in python

The best way to describe what a Calculator does and how it should behave is by example: To simulate a diffraction pattern from a single protein, you can use the SingFELPhotonDiffractor. See this example for a standalone SFX simulation, and this example for a start-to-end simulation.

Calculators and Parameters

Each Calculator is constructed by the statement

>>> calculator = <CalculatorClassName>(parameters, input_path, output_path)

where parameters is an instance of the corresponding Parameters class, input_path and output_path are filenames or directory names. If the output path is omitted, a default path will be constructed internally.

The parameters object itself, is constructed very similarily:

>>> parameters = <CalculatorClassName>Parameters(**kwargs)

where **kwargs is a sequence of key=value pairs. Here, the user has to consult the documentation of the Calculator/Parameters class to figure out the names and possible values of each key. E.g. in an interactive ipython session, one could

>>> ?SingFELPhotonDiffractorParameters

to print the documentation of the parameters corresponding to the diffraction simulator SingFELPhotonDiffractor.

NOTE: You will find that parts of the documentation are severely misleading or simply outdated. Whenever you come across such a case, please either (a) correct in your development repo and submit a pull request or (b) submit a ticket under "Issues" in eucall-software/simex_platform