.. _execute-sceptic-label:

Execute ScEpTIC Analysis
========================

.. |techrep| raw:: html

    <a href="http://hdl.handle.net/10589/147444" target="_blank">technical report</a>

For each program you need to analyze with ScEpTIC, you need to:

1. Generate the LLVM IR of your program, as we describe in :ref:`compilation-label`
2. Configure ScEpTIC and your target architecture, as we describe in :ref:`configuration-label`
3. Configure the system model, as we describe in :ref:`system-model-label`

To run our analysis, we first need to import the ScEpTIC module and our configuration file.
Then, we initialize ScEpTIC using the ``init()`` function.
Finally, we need to call the ``run_analysis()`` module to execute the configured analysis.

For example, if our configuration is saved inside ``config.py``::
    
    import ScEpTIC
    import config

    sc = ScEpTIC.init(config)
    sc.execute_analysis()

This runs all the analysis that we enabled in the configuration file.


ScEpTIC exposes also a ``run_single_analysis(analysis_name)`` method, where ``analysis_name`` is the name of the analysis to run.
For example, if we want to execute the analysis for evaluating system energy consumption, you can run::

    import ScEpTIC
    import config

    sc = ScEpTIC.init(config)
    self.run_single_analysis('energy')

Analysis are stored in dedicated folders inside ``ScEpTIC/analysis``.
Execute your analysis using ``pypy3`` to ensure higher simulation speeds::

    pypy3 your_run.py

When ScEpTIC terminates the analysis execution, it saves the analysis results inside a sub-directory that is inside the ``save_dir`` directory that we specified in the configuration file.
Each result directory contains three sub-folders:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution
- ``analysis``: contains the output of specific analysis, its custom metrics, and the simulation termination reason

Create your analysis
--------------------
To create your custom analysis, you need to create its logic by extending the ``ScEpTICAnalysis`` base class from ``ScEpTIC/analysis`` and its configuration by extending ``ScEpTICBaseConfig`` from ``ScEpTIC/config/config``.
Next, you need to create a directory inside ``ScEpTIC/analysis``, where you place your new classes and these three files::

    your_analysis/__init__.py
    your_analysis/main.py
    your_analysis/config.py

``__init__.py`` must be empty, whereas ``main.py`` and ``config.py`` must provide a specific function to get the analysis and its configuration, respectively.

``main.py``::

    def get_analysis(sc):
        return YourAnalysis(sc)


``config.py``::

    def get_config(main_config):
        return YourAnalysisConfig(main_config)