Simulation.Aivika.Experiment

Tested with: GHC 7.4.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 simulations 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.

Documentation

data Experiment

It defines the simulation experiment.

Constructors

Experiment

Fields

experimentSpecs :: Specs

The simulation specs for the experiment.

experimentRunCount :: Int

How many simulation runs should be launched.

experimentDirectoryName :: DirectoryName

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.

experimentGenerators :: [Generator]

The experiment generators.

experimentIndexHtml :: Experiment -> [Reporter] -> FilePath -> IO ()

Create the index.html file after the simulation is finished in the specified directory.

defaultExperiment :: Experiment

The default experiment.

runExperiment :: Experiment -> Simulation ExperimentData -> IO ()

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

runExperimentParallel :: Experiment -> Simulation ExperimentData -> IO ()

Run the simulation experiment parallelly.

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.

data ExperimentData

It describes the source simulation data used in the experiment.

Constructors

ExperimentData

Fields

experimentQueue :: EventQueue

Return the event queue.

experimentSignalInIntegTimes :: Signal Double

The signal triggered in the integration time points.

experimentSignalInStartTime :: Signal Double

The signal triggered in the start time.

experimentSignalInStopTime :: Signal Double

The signal triggered in the stop time.

experimentSeries :: Map String SeriesEntity

The simulation entitities with labels as keys.

experimentDataInStartTime :: EventQueue -> [(String, SeriesEntity)] -> Simulation ExperimentData

Prepare data for the simulation experiment in start time from the series with the specified labels.

experimentSeriesProviders :: ExperimentData -> [String] -> [SeriesProvider]

Return the SeriesProvider values from the experiment data by the specified labels.

experimentMixedSignal :: ExperimentData -> [SeriesProvider] -> Signal ()

Get a mixed signal for the specified providers based on the experimental data. This signal is triggered when the provided signals are triggered. The mixed signal is also triggered in the integration time points if there is at least one provider without signal.

class Series s where

Represents the series. It is usually something, or an array of something, or a list of such values which can be simulated.

Methods

seriesEntity :: String -> s -> SeriesEntity

Return the simulatable entity with the specified name for the given series.

Instances

Series s => Series [s]

Series (Var Double)

Series (Var Int)

Series (Var String)

Series (UVar Double)

Series (UVar Int)

Series (Ref Double)

Series (Ref Int)

Series (Ref String)

Series (Dynamics Double)

Series (Dynamics Int)

Series (Dynamics String)

Series (Simulation Double)

Series (Simulation Int)

Series (Simulation String)

(Show i, Ix i, Series s) => Series (Array i s)

data SeriesEntity

Defines the simulatable entity.

Constructors

SeriesEntity

Fields

seriesProviders :: [SeriesProvider]

Return the providers for the entity.

data SeriesProvider

This is provider of the simulatable data.

Constructors

SeriesProvider

Fields

providerName :: String

Return the name.

providerToDouble :: Maybe (Dynamics Double)

Try to return the data as double values.

providerToInt :: Maybe (Dynamics Int)

Try to return the data as integers.

providerToString :: Maybe (Dynamics String)

Try to return the data as strings.

providerSignal :: Maybe (Signal ())

Try to get a signal for the data, which is actual for the Ref references and the Var variables. You should not provide such a signal if the data are calculated only in the integration time points, which is true for the integrals, for example.

class View v 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 -> Generator

Create a generator of the reporter.

Instances

View LastValueView

View TableView

data Generator

This is a generator of the reporter.

Constructors

Generator

Fields

generateReporter :: Experiment -> FilePath -> IO Reporter

Generate a reporter for the specified directory, where the index.html file will be saved for the current simulation experiment.

data Reporter

Defines what creates the simulation reports.

Constructors

Reporter

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 -> Dynamics (Dynamics ())

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.

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

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

data DirectoryName

Specifies the directory name, unique or writable.

Constructors

WritableDirectoryName String

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

UniqueDirectoryName String

The directory which is always unique, when a prefix is added to the name in case of need.

resolveDirectoryName :: Maybe FilePath -> DirectoryName -> Map String String -> IO String

Resolve the directory name relative to the passed in directory as the first argument, replacing the specified strings according the map.

data FileName

Specifies the file name, unique or writable.

Constructors

WritableFileName String String

The file which is overwritten in case if it existed before. The first field defines a name or its prototype. The second field is the file extension.

UniqueFileName String String

The file which is always unique, when a prefix is added to the name in case of need. The first field defines a name or its prototype. The second field is the file exension.

resolveFileName :: Maybe FilePath -> FileName -> Map String String -> IO String

Resolve the file name relative to the passed in directory as the first argument, replacing the specified strings according the map.