Copyright	Copyright (c) 2012-2017 David Sorokin <david.sorokin@gmail.com>
License	BSD3
Maintainer	David Sorokin <david.sorokin@gmail.com>
Stability	experimental
Safe Haskell	Safe-Inferred
Language	Haskell2010

Simulation.Aivika.Experiment.Types

Description

Tested with: GHC 8.0.1

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.

Synopsis

data Experiment = Experiment {
- experimentSpecs :: Specs
- experimentTransform :: ResultTransform
- experimentLocalisation :: ResultLocalisation
- experimentRunCount :: Int
- experimentTitle :: String
- experimentDescription :: String
- experimentVerbose :: Bool
- experimentNumCapabilities :: IO Int
}
defaultExperiment :: Experiment
class ExperimentRendering r where
- data ExperimentContext r :: *
- type ExperimentEnvironment r :: *
- type ExperimentMonad r :: * -> *
- liftExperiment :: r -> ExperimentMonad r a -> IO a
- prepareExperiment :: Experiment -> r -> ExperimentMonad r (ExperimentEnvironment r)
- renderExperiment :: Experiment -> r -> [ExperimentReporter r] -> ExperimentEnvironment r -> ExperimentMonad r ()
- onExperimentCompleted :: Experiment -> r -> ExperimentEnvironment r -> ExperimentMonad r ()
- onExperimentFailed :: Exception e => Experiment -> r -> ExperimentEnvironment r -> e -> ExperimentMonad r ()
data ExperimentGenerator r = ExperimentGenerator {
- generateReporter :: Experiment -> r -> ExperimentEnvironment r -> ExperimentMonad r (ExperimentReporter r)
}
class ExperimentRendering r => ExperimentView v r where
- outputView :: v -> ExperimentGenerator r
data ExperimentData = ExperimentData {
- experimentResults :: Results
- experimentPredefinedSignals :: ResultPredefinedSignals
}
data ExperimentReporter r = ExperimentReporter {
- reporterInitialise :: ExperimentMonad r ()
- reporterFinalise :: ExperimentMonad r ()
- reporterSimulate :: ExperimentData -> Composite ()
- reporterContext :: ExperimentContext r
}
runExperiment :: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r)) => Experiment -> [ExperimentGenerator r] -> r -> Simulation Results -> IO (Either SomeException ())
runExperimentParallel :: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r)) => Experiment -> [ExperimentGenerator r] -> r -> Simulation Results -> IO (Either SomeException ())
runExperimentWithExecutor :: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r)) => ([IO ()] -> IO a) -> Experiment -> [ExperimentGenerator r] -> r -> Simulation Results -> IO (Either SomeException a)

Documentation

data Experiment Source #

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.
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.

defaultExperiment :: Experiment Source #

The default experiment.

class ExperimentRendering r where Source #

It allows rendering the simulation results in an arbitrary way.

Associated Types

data ExperimentContext r :: * Source #

Defines a context used when rendering the experiment.

type ExperimentEnvironment r :: * Source #

Defines the experiment environment.

type ExperimentMonad r :: * -> * Source #

Defines the experiment monad type.

Methods

liftExperiment :: r -> ExperimentMonad r a -> IO a Source #

Lift the experiment computation.

prepareExperiment :: Experiment -> r -> ExperimentMonad r (ExperimentEnvironment r) Source #

Prepare before rendering the experiment.

renderExperiment :: Experiment -> r -> [ExperimentReporter r] -> ExperimentEnvironment r -> ExperimentMonad r () Source #

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

onExperimentCompleted :: Experiment -> r -> ExperimentEnvironment r -> ExperimentMonad r () Source #

It is called when the experiment has been completed.

onExperimentFailed :: Exception e => Experiment -> r -> ExperimentEnvironment r -> e -> ExperimentMonad r () Source #

It is called when the experiment rendering has failed.

Instances

Instances details

ExperimentRendering (FileRenderer a) Source #	Saving the results of simulation in files when running the experiment.
Instance details Defined in Simulation.Aivika.Experiment.Base.FileRenderer Associated Types data ExperimentContext (FileRenderer a) Source # type ExperimentEnvironment (FileRenderer a) Source # type ExperimentMonad (FileRenderer a) :: Type -> Type Source # Methods liftExperiment :: FileRenderer a -> ExperimentMonad (FileRenderer a) a0 -> IO a0 Source # prepareExperiment :: Experiment -> FileRenderer a -> ExperimentMonad (FileRenderer a) (ExperimentEnvironment (FileRenderer a)) Source # renderExperiment :: Experiment -> FileRenderer a -> [ExperimentReporter (FileRenderer a)] -> ExperimentEnvironment (FileRenderer a) -> ExperimentMonad (FileRenderer a) () Source # onExperimentCompleted :: Experiment -> FileRenderer a -> ExperimentEnvironment (FileRenderer a) -> ExperimentMonad (FileRenderer a) () Source # onExperimentFailed :: Exception e => Experiment -> FileRenderer a -> ExperimentEnvironment (FileRenderer a) -> e -> ExperimentMonad (FileRenderer a) () Source #
ExperimentRendering (WebPageRenderer a) Source #	Rendering a web page with results when running the simulation experiment.
Instance details Defined in Simulation.Aivika.Experiment.Base.WebPageRenderer Associated Types data ExperimentContext (WebPageRenderer a) Source # type ExperimentEnvironment (WebPageRenderer a) Source # type ExperimentMonad (WebPageRenderer a) :: Type -> Type Source # Methods liftExperiment :: WebPageRenderer a -> ExperimentMonad (WebPageRenderer a) a0 -> IO a0 Source # prepareExperiment :: Experiment -> WebPageRenderer a -> ExperimentMonad (WebPageRenderer a) (ExperimentEnvironment (WebPageRenderer a)) Source # renderExperiment :: Experiment -> WebPageRenderer a -> [ExperimentReporter (WebPageRenderer a)] -> ExperimentEnvironment (WebPageRenderer a) -> ExperimentMonad (WebPageRenderer a) () Source # onExperimentCompleted :: Experiment -> WebPageRenderer a -> ExperimentEnvironment (WebPageRenderer a) -> ExperimentMonad (WebPageRenderer a) () Source # onExperimentFailed :: Exception e => Experiment -> WebPageRenderer a -> ExperimentEnvironment (WebPageRenderer a) -> e -> ExperimentMonad (WebPageRenderer a) () Source #

data ExperimentGenerator r Source #

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

Constructors

ExperimentGenerator
Fields generateReporter :: Experiment -> r -> ExperimentEnvironment r -> ExperimentMonad r (ExperimentReporter r) Generate a reporter.

class ExperimentRendering r => ExperimentView v r where Source #

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 Source #

Create a generator of the reporter.

Instances

Instances details

ExperimentView ExperimentSpecsView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.ExperimentSpecsView Methods outputView :: ExperimentSpecsView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView FinalStatsView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.FinalStatsView Methods outputView :: FinalStatsView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView FinalTableView (FileRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.FinalTableView Methods outputView :: FinalTableView -> ExperimentGenerator (FileRenderer a) Source #
ExperimentView FinalTableView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.FinalTableView Methods outputView :: FinalTableView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView InfoView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.InfoView Methods outputView :: InfoView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView LastValueView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.LastValueView Methods outputView :: LastValueView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView TableView (FileRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.TableView Methods outputView :: TableView -> ExperimentGenerator (FileRenderer a) Source #
ExperimentView TableView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.TableView Methods outputView :: TableView -> ExperimentGenerator (WebPageRenderer a) Source #
ExperimentView TimingStatsView (WebPageRenderer a) Source #
Instance details Defined in Simulation.Aivika.Experiment.Base.TimingStatsView Methods outputView :: TimingStatsView -> ExperimentGenerator (WebPageRenderer a) Source #

data ExperimentData Source #

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.

data ExperimentReporter r Source #

Defines what creates the simulation reports by the specified renderer.

Constructors

ExperimentReporter
Fields reporterInitialise :: ExperimentMonad r () Initialise the reporting before the simulation runs are started. reporterFinalise :: ExperimentMonad r () Finalise the reporting after all simulation runs are finished. reporterSimulate :: ExperimentData -> Composite () Start the simulation run in the start time. reporterContext :: ExperimentContext r Return a context used by the renderer.

runExperiment Source #

Arguments

:: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r))
=> Experiment	the simulation experiment to run
-> [ExperimentGenerator r]	generators used for rendering
-> r	the rendering backend
-> Simulation Results	the simulation results received from the model
-> IO (Either SomeException ())

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

runExperimentParallel Source #

Arguments

:: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r))
=> Experiment	the simulation experiment to run
-> [ExperimentGenerator r]	generators used for rendering
-> r	the rendering backend
-> Simulation Results	the simulation results received from the model
-> IO (Either SomeException ())

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.

runExperimentWithExecutor Source #

Arguments

:: (ExperimentRendering r, Monad (ExperimentMonad r), MonadIO (ExperimentMonad r), MonadException (ExperimentMonad r))
=> ([IO ()] -> IO a)	an executor that allows parallelizing the simulation if required
-> Experiment	the simulation experiment to run
-> [ExperimentGenerator r]	generators used for rendering
-> r	the rendering backend
-> Simulation Results	the simulation results received from the model
-> IO (Either SomeException a)

Run the simulation experiment with the specified executor.