Simulation.Aivika.Experiment.Types

Tested with: GHC 7.8.3

The module defines the simulation experiments. They automate the process of generating and analyzing the results. Moreover, this module is open to extensions, allowing you to define your own output views for the simulation results, for example, such views that would allow saving the results in PDF or as charts. To decrease the number of dependencies, such possible extenstions are not included in this package, although simple views are provided.

General Definitions

data Experiment

It defines the simulation experiment with the specified rendering backend and its bound data.

Constructors

Experiment

Fields

experimentSpecs :: Specs

The simulation specs for the experiment.

experimentTransform :: ResultTransform

How the results must be transformed before rendering.

experimentLocalisation :: ResultLocalisation

Specifies a localisation applied when rendering the experiment.

experimentRunCount :: Int

How many simulation runs should be launched.

experimentDirectoryName :: ExperimentFilePath

The directory in which the output results should be saved.

experimentTitle :: String

The experiment title.

experimentDescription :: String

The experiment description.

experimentVerbose :: Bool

Whether the process of generating the results is verbose.

experimentNumCapabilities :: IO Int

The number of threads used for the Monte-Carlo simulation if the executable was compiled with the support of multi-threading.

class ExperimentRendering r a | r -> a where

It allows rendering the simulation results in an arbitrary way.

Methods

renderExperiment :: Experiment -> r -> [ExperimentReporter a] -> FilePath -> IO ()

Render the experiment after the simulation is finished, for example, creating the index.html file in the specified directory.

Instances

ExperimentRendering WebPageRenderer WebPageWriter

defaultExperiment :: Experiment

The default experiment.

runExperiment

Arguments

:: ExperimentRendering r a

=> Experiment

the simulation experiment to run

-> [ExperimentGenerator r a]

generators used for rendering

-> r

the rendering backend

-> Simulation Results

the simulation results received from the model

-> IO ()

Run the simulation experiment sequentially. For example, it can be a Monte-Carlo simulation dependentent on the external Parameter values.

runExperimentParallel

Arguments

:: ExperimentRendering r a

=> Experiment

the simulation experiment to run

-> [ExperimentGenerator r a]

generators used for rendering

-> r

the rendering backend

-> Simulation Results

the simulation results received from the model

-> IO ()

Run the simulation experiment in parallel.

Make sure that you compile with -threaded and supply +RTS -N2 -RTS to the generated Haskell executable on dual core processor, or you won't get any parallelism. Generally, the mentioned N parameter should correspond to the number of cores for your processor.

In case of need you might want to specify the number of threads directly with help of experimentNumCapabilities, although the real number of parallel threads can depend on many factors.

data ExperimentData

It describes the source simulation data used in the experiment.

Constructors

ExperimentData

Fields

experimentResults :: Results

The simulation results used in the experiment.

experimentPredefinedSignals :: ResultPredefinedSignals

The predefined signals provided by every model.

class ExperimentRendering r a => ExperimentView v r a | r -> a where

Defines a view in which the simulation results should be saved. You should extend this type class to define your own views such as the PDF document.

Methods

outputView :: v -> ExperimentGenerator r a

Create a generator of the reporter.

Instances

WebPageRendering r => ExperimentView LastValueView r WebPageWriter

WebPageRendering r => ExperimentView TableView r WebPageWriter

WebPageRendering r => ExperimentView TimingStatsView r WebPageWriter

WebPageRendering r => ExperimentView FinalStatsView r WebPageWriter

WebPageRendering r => ExperimentView ExperimentSpecsView r WebPageWriter

WebPageRendering r => ExperimentView FinalTableView r WebPageWriter

data ExperimentGenerator r a

This is a generator of the reporter with the specified rendering backend.

Constructors

ExperimentGenerator

Fields

generateReporter :: Experiment -> r -> FilePath -> IO (ExperimentReporter a)

Generate a reporter bound up with the specified directory.

data ExperimentReporter a

Defines what creates the simulation reports by the specified renderer.

Constructors

ExperimentReporter

Fields

reporterInitialise :: IO ()

Initialise the reporting before the simulation runs are started.

reporterFinalise :: IO ()

Finalise the reporting after all simulation runs are finished.

reporterSimulate :: ExperimentData -> Event DisposableEvent

Start the simulation run in the start time and return a finalizer that will be called in the stop time after the last signal is triggered and processed.

reporterRequest :: a

Return data requested by the renderer.

data ExperimentFilePath

Specifies the file name, unique or writable, which can be appended with extension if required.

Constructors

WritableFilePath FilePath

The file which is overwritten in case if it existed before.

UniqueFilePath FilePath

The file which is always unique, when an automatically generated suffix is added to the name in case of need.

resolveFilePath :: FilePath -> ExperimentFilePath -> IO FilePath

Resolve the file path relative to the specified directory passed in the first argument and taking into account a possible requirement to have an unique file name.

expandFilePath :: ExperimentFilePath -> Map String String -> ExperimentFilePath

Expand the file path using the specified table of substitutions.

mapFilePath :: (FilePath -> FilePath) -> ExperimentFilePath -> ExperimentFilePath

Transform the file path using the specified function.

Web Page Rendering

class ExperimentRendering r WebPageWriter => WebPageRendering r

A subclass of renderers that know how to save the index.html file when rendering the simulation experiment.

Instances

WebPageRendering WebPageRenderer

data WebPageRenderer

It defines the web page renderer for simulation Experiment.

Constructors

WebPageRenderer

Instances

WebPageRendering WebPageRenderer

ExperimentRendering WebPageRenderer WebPageWriter

data WebPageWriter

It replies to the requests made by the web page renderer.

Constructors

WebPageWriter

Fields

reporterWriteTOCHtml :: Int -> HtmlWriter ()

Return a TOC (Table of Contents) item for the HTML index file after the finalisation function is called, i.e. in the very end. The agument specifies the ordered number of the item.

You should wrap your HTML in writeHtmlListItem.

reporterWriteHtml :: Int -> HtmlWriter ()

Return an HTML code for the index file after the finalisation function is called, i.e. in the very end. The agument specifies the ordered number of the item.

Instances

ExperimentRendering WebPageRenderer WebPageWriter

WebPageRendering r => ExperimentView LastValueView r WebPageWriter

WebPageRendering r => ExperimentView TableView r WebPageWriter

WebPageRendering r => ExperimentView TimingStatsView r WebPageWriter

WebPageRendering r => ExperimentView FinalStatsView r WebPageWriter

WebPageRendering r => ExperimentView ExperimentSpecsView r WebPageWriter

WebPageRendering r => ExperimentView FinalTableView r WebPageWriter

type WebPageGenerator r = ExperimentGenerator r WebPageWriter

A convenient type synonym for describing the web page generators.