.. _structure: ******************** Repository Structure ******************** At the root of the repository there are six directories: - build - ci - Docker - docs - examples - fitbenchmarking ################# Build (``build``) ################# This directory contains scripts to allow for installing packages such as Mantid through setuptools. ######################### CI (``ci``) ######################### We use `GitHub Actions `__ to run our Continuous Integration tests. The specific tests run are defined in a series of Bash scripts, which are stored in this folder. ########################## Container (``Container``) ########################## The continuous integration process on Github Actions currently run on a container, and this directory holds the Containerfiles. The container is hosted on the Github Container Registry (ghcr.io). ``Containerfile`` builds into a container that includes all optional third party software that FitBenchmarking can work with. The version tagged as "latest" on ghcr is updated via github actions when the file is edited. This can be locally built via podman with: .. code-block:: bash podman build Container/ -t fitbenchmarking: where ```` is, e.g., ``latest``. ######################## Documentation (``docs``) ######################## The documentation for FitBenchmarking is stored in this folder under ``source``. A local copy of the documentation can be build using ``make html`` in the ``build`` directory. ####################### Examples (``examples``) ####################### Examples is used to store sample problem files and options files. A collection of problem files can be found organised into datasets within the ``examples/benchmark_problems/`` directory. An options template file and a prewritten options file to run a full set of minimizers is also made available in the ``examples/`` directory. ################################################### FitBenchmarking Package (:py:mod:`fitbenchmarking`) ################################################### The main FitBenchmarking package is split across several directories with the intention that it is easily extensible. The majority of these directories are source code, with exceptions being Templates, Test Files, and System Tests. Each file that contains source code will have a directory inside it called ``tests``, which contains all of the tests for that section of the code. Benchmark Problems (``benchmark_problems``) =========================================== This is a copy of the NIST benchmark problems from `examples/benchmark_problems`. These are the default problems that are run if no problem is passed to the ``fitbenchmarking`` command, and is copied here so that it is distributed with the package when installed using, say, `pip`. CLI (:py:mod:`~fitbenchmarking.cli`) ==================================== The CLI directory is used to define all of the entry points into the software. Currently this is just the main `fitbenchmarking` command. Controllers (:py:mod:`~fitbenchmarking.controllers`) ==================================================== In FitBenchmarking, controllers are used to interface with third party minimizers. The controllers directory holds a base controller class (:class:`~fitbenchmarking.controllers.base_controller.Controller`) and all its subclasses, each of which of which interfaces with a different fitting package. The controllers currently implemented are described in :ref:`fitting_option` and :ref:`minimizer_option`. New controllers can be added by following the instructions in :ref:`controllers`. Core (:py:mod:`~fitbenchmarking.core`) ====================================== This directory holds all code central to FitBenchmarking. For example, this manages calling the correct parser and controller, as well as compiling the results into a data object. Hessian (:py:mod:`~fitbenchmarking.Hessian`) ============================================== This directory holds the :class:`~fitbenchmarking.hessian.base_hessian.Hessian` class, and subclasses, which are used by the controllers to approximate second derivatives. Currently available options are described in :ref:`fitting_option`, and new Hessians can be added by following the instructions in :ref:`hessian_extend`. Jacobian (:py:mod:`~fitbenchmarking.jacobian`) ============================================== This directory holds the :class:`~fitbenchmarking.jacobian.base_jacobian.Jacobian` class, and subclasses, which are used by the controllers to approximate derivatives. Currently available options are described in :ref:`jacobian_option`, and new numerical Jacobians can be added by following the instructions in :ref:`jacobian_extend`. Test Files (``test_files``) ================================= The test files are used in some tests where full problem files are required. These are here so that the examples can be moved without breaking the tests. Parsing (:py:mod:`~fitbenchmarking.parsing`) ============================================ The parsers read raw data into a format that FitBenchmarking can use. This directory holds a base parser, :class:`~fitbenchmarking.parsing.base_parser.Parser` and all its subclasses. Each subclass implements a parser for a specific file format. Information about existing parsers can be found in :ref:`problem_def`, and see :ref:`parsers` for instructions on extending these. Results Processing (:py:mod:`~fitbenchmarking.results_processing`) ================================================================== All files that are used to generate output are stored here. This includes index pages, text/html tables, plots, and support pages. Information about the tables we provide can be found in :ref:`output`, and instructions on how to add further tables and change the formatting of the displayed information can be found in :ref:`extending_outputs`. System Tests (``systests``) =========================== FitBenchmarking runs regression tests to check that the accuracy results do not change with updates to the code. These tests run fitbenchmarking against a subset of problems (in subdirectories of `/fitbenchmarking/test_files/`), and compares the text output with that stored in `/fitbenchmarking/systests/expected_results/`. Templates (``templates``) ========================= Files in Templates are used to create the resulting html pages, and are a combination of css, html, and python files. The python files in this directory are scripts to update the css and html assets. Instructions on updating these can be found in :ref:`templates`. Utils (:py:mod:`~fitbenchmarking.utils`) ======================================== This directory contains utility functions that do not fit into the above sections. This includes the :class:`~fitbenchmarking.utils.options.Options` class (see :ref:`options_extend` to extend) and :class:`~fitbenchmarking.utils.fitbm_result.FittingResult` class, as well as functions for logging and directory creation.