Structure of the source code

In the sections and documents referenced below, the best place to learn about the Reveal code base, and the right place to type and test code snippets from this tutorial is Reveal’s Python console. We recommend users familiar themselves with that tool before proceeding further.

The package and its sub-packages

The top level package is, for historical reasons, called kromatography. Consequently, using the application’s tools and objects means importing from that package. For example:

from kromatography import version_info

Following standard industry practices, the top level package is split into the following subpackages:

  • kromatography.io: contains all functions for reading and writing objects and project files to and from disk. That includes the storage of User Data.
  • kromatography.solve: contains modules and objects to execute the CADET solver on one or more simulations.
  • kromatography.utils: contains miscellaneous modules to execute small tasks needed across the application: application initialization, file management, logging, unit definitions and conversions, etc.
  • kromatography.plotting: contains the models and views to build the chromatograms and column animation plots.
  • kromatography.model: contains the abstractions for all chromatography elements used in the application: Experiment, Simulation, Product, ... as well as more complex data containers like PerformanceData displayed in the performance panel, XYData storing data behind chromatograms timeseries, ...
  • kromatography.compute: contains modules and objects to build optimizer, and compute performance parameters.
  • kromatography.ui: contains all view elements as well as UI objects for all modal windows popping up when using the application: new data builders, new optimizer or simulation group builders, etc.

The following sub-packages are also listed in the documentation but are unlikely to be used in a user script, as they support launching the main application or very low level UI elements:

  • kromatography.app: contains the application object to launch the main application Graphical User Interface. If one wants to start an application from a study built programmatically, kromatography.utils.api.launch_app_for_study() instead.

The API modules

Finally, each one of these subpackages contains an api module which contains the functions which are part of the Application Program Interface (API). That’s the subset of functionalities which are expected to be useful to external Reveal users and developers, and expected to remain stable. They are therefore suitable to become the building blocks of custom user scripts.

Consequently, if a developer would like to know what, for example, the IO sub-package contains, and what might be useful to build scripts, (s)he should explore the content of the kromatography.io.api module. That can be done in reveal_python_console by typing the following:

>>> from kromatography.io.api import

and hitting the <TAB> key in the Python console, to get all the options available in that API module.

Factories sub-packages

As mentioned above, multiple subpackages, such as kromatography.model, contain a factories sub-package, which contains utilities to guide developers to build objects the right way. For example, the best way to programmatically build a simulation from an experiment is to do the following:

>>> # Let's load some experiment data first:
>>> from kromatography.data.api import load_tutorial_project
>>> study = load_tutorial_project()
>>> exp = study.search_experiment_by_name("Run_1")
>>> from kromatography.model.factories.api import build_simulation_from_experiment
>>> build_simulation_from_experiment(exp)

The later command will build a proper simulation from the Run_1 experiment, using all default values for the other parameters.

>> build_simulation_from_experiment?

in the Python console to learn what the other parameters are, and what default values were used. (Then, hit the q or ESC keys to exit that help.)

Users will find useful to inspect the content of the following factories sub-packages: kromatography.model.factories (to build data elements), and kromatography.compute.factories (to build simulation grids and optimizers). There again, the api modules expose the most commonly used functions.