Vous avez re莽u un message "Your GitLab account has been locked ..." ? Pas d'inqui茅tude : lisez cet article https://docs.gricad-pages.univ-grenoble-alpes.fr/help/unlock/

Commit 2b650fe0 authored by Alexis Brenon's avatar Alexis Brenon
Browse files

馃摑 馃毀 Update environment documentation

parent d53bf290
......@@ -24,11 +24,8 @@ end
-- luacheck: push no unused args
--- Integrate current observation from the environment.
-- @tparam table state The current state of the environment
-- @tparam torch.Tensor state.observation The actual observations
-- @tparam boolean state.terminal Is this state terminal?
-- @tparam environment.ObservableState state The current state of the environment
-- @return `self`
-- @see environment.BaseEnvironment.observable_state
function class:integrate_observation(state)
io.stderr:write(string.format(
"WARNING: %s:%s - Not implemented",
......
--- Base class/interface from which inherit to implement an environment
--- Abstract class from which inherit to implement an environment
-- @classmod environment.BaseEnvironment
-- @alias class
-- @inherit true
-- @see ArcadesComponent
-- @author Alexis BRENON <alexis.brenon@imag.fr>
local torch = require('torch')
......@@ -9,29 +11,19 @@ local arcades = require('arcades')
local module = {}
local class, super = torch.class('BaseEnvironment', 'ArcadesComponent', module)
--- Attributes
-- @section attributes
-------
-- Observable state of an environment perceived by an agent
-- @tfield torch.Tensor observation Observation data
-- @tfield boolean terminal Is the state terminal?
-- @table observable_state
--- @section end
--- Abstract constructor
--- Default constructor.
-- @tparam ArcadesComponent.InitArgument args
function class:__init(args)
super.__init(self, args)
end
--- Interface
-- @section interface
--- Abstract Methods
-- @section abstract-methods
--- Returns the current visible state of the environment
-- @todo Do two calls to this function return same values (stochastic or not?)
-- @treturn table @{observable_state|Observable state} of the environment
-- @warn Do two calls to this function return same values (stochastic or not?)
-- @treturn environment.ObservableState Observable state of the environment
function class:get_observable_state()
error(string.format(
"%s:%s - Not implemented",
......@@ -42,9 +34,9 @@ end
-- luacheck: push no unused args
--- Perform an action on the world that change its internal state
-- @tparam number action_index The index of the action to perform
-- @return self
--- Perform an action on the world that change its internal state.
-- @tparam integer action_index The index of the action to perform
-- @return `self`
function class:perform_action(action_index)
error(string.format(
"%s:%s - Not implemented",
......@@ -55,7 +47,7 @@ function class:perform_action(action_index)
end
-- luacheck: pop
--- Get reward obtained from the last action
--- Get reward obtained from the last action.
-- @treturn number A reward
function class:get_reward()
error(string.format(
......@@ -66,7 +58,7 @@ function class:get_reward()
2)
end
--- Get the possible actions that environment accepts
--- Get the possible actions that environment accepts.
-- @treturn table A table of accepted actions
function class:actions()
error(string.format(
......@@ -77,7 +69,7 @@ function class:actions()
end
--- Return the action index of the expected action for the current state.
-- @treturn number Index of the expected action
-- @treturn integer Index of the expected action
function class:get_true_action()
error(string.format(
"%s:%s - Not implemented",
......@@ -86,8 +78,8 @@ function class:get_true_action()
), 2)
end
--- (Re)Initialize the environment
-- @return self
--- (Re)Initialize the environment.
-- @return `self`
function class:reset()
return self
end
......
--- Debug environment that produces dummy states
-- @classmod environment.DebugEnvironment
-- @alias class
-- @inherit true
-- @see environment.BaseEnvironment
-- @see ArcadesComponent
-- @author Alexis BRENON <alexis.brenon@imag.fr>
-- luacheck: no self
......@@ -13,52 +15,73 @@ assert(environment.BaseEnvironment)
local module = {}
local class, super = torch.class('DebugEnvironment', 'BaseEnvironment', module)
--- Default constructor
--- Fields
-- @section fields
--- Is current state terminal?
-- @tfield boolean self.terminal
--- @section end
--- Default constructor.
-- @tparam ArcadesComponent.InitArgument args
function class:__init(args)
super.__init(self, args)
self.terminal = nil
end
--- Overriden methods
-- @section methods-overriden
--- Public Methods
-- @section public-methods
--- Overriden method
--- Returns the current visible state of the environment
-- @treturn environment.ObservableState Observable state of the environment
-- @override true
-- @see BaseEnvironment:get_observable_state
function class:get_observable_state()
return {observation = torch.Tensor(1,1,1):fill((self.terminal and 2) or 1), terminal=self.terminal}
end
--- Overriden method
--- Perform an action on the world that change its internal state.
--
-- For this debug environment, just switch the terminal signal.
-- @return `self`
-- @override true
-- @see BaseEnvironment:perform_action
function class:perform_action()
self.terminal = not self.terminal
end
--- Overriden method
--- Get reward obtained from the last action.
-- @treturn number A reward (`1`)
-- @override true
-- @see BaseEnvironment:get_reward
function class:get_reward()
return 1
end
--- Overriden method
--- Get the possible actions that environment accepts.
-- @treturn table A table of accepted actions (`{1}`)
-- @override true
-- @see BaseEnvironment:actions
function class:actions()
return {1}
end
--- Overriden method
--- Return the action index of the expected action for the current state.
-- @treturn integer Index of the expected action (`1`)
-- @override true
-- @see BaseEnvironment:get_true_action
function class:get_true_action()
return 1
end
--- Overriden method
--- (Re)Initialize the environment.
-- @return `self`
-- @override true
-- @see BaseEnvironment:reset
function class:reset()
self.terminal = false
return self
end
--- @section end
return module.DebugEnvironment
--- A set of different environments on which an @{agent} can act.
--
-- List of the classes in this package:
-- <ul>
-- <li>@{environment.BaseEnvironment|BaseEnvironment}</li>
-- <li>@{environment.DebugEnvironment|DebugEnvironment}</li>
-- <li>@{environment.SweetHomeInferredGenerated|SweetHomeInferredGenerated}</li>
-- <li>@{environment.NoisySweetHomeInferredGenerated|NoisySweetHomeInferredGenerated}</li>
-- <li>@{environment.SweetHomeInferred|SweetHomeInferred}</li>
-- </ul>
--
-- * @{environment.BaseEnvironment|BaseEnvironment}
-- * @{environment.DebugEnvironment|DebugEnvironment}
--
-- List of sub-packages:
--
-- * @{environment.smarthome}
-- * @{environment.states|states}
--
-- After creation, environments need to be initialized/reset to set them in a
-- coherent state, calling the @{environment.BaseEnvironment:reset|reset}
-- function.
--
-- @module environment
-- @alias package
-- @package environment
-- @author Alexis BRENON <alexis.brenon@imag.fr>
--- Data Types
-- @section data-types
--- Observable state of an environment perceived by an agent.
-- @tfield torch.Tensor/tensor.md/ observation Observation data
-- @tfield boolean terminal Is the state terminal?
-- @table ObservableState
--- @section end
return require('arcades.utils.package_loader')(...)
--- Base abstract class from which inherit to implement any data
-- rendering strategy.
-- @classmod environment.states.datarenderer.DataRenderer
-- @alias class
-- @inherit true
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local arcades = require('arcades')
......@@ -5,10 +13,17 @@ local arcades = require('arcades')
local _M = {}
local class, super = torch.class("DataRenderer", "ArcadesComponent", _M)
--- Default constructor.
-- @tparam ArcadesComponent.InitArgument args
-- @mtodo Fix usage of `dump`
function class:__init(args)
super.__init(self, args)
end
--- Abstract Methods
-- @section abstract-methods
--- Render given data.
function class:render()
if torch.typename(self) == "DataRenderer" then
error(
......
--- A class to generate an image from raw data.
-- @classmod environment.states.datarenderer.GraphicalDataRenderer
-- @alias class
-- @inherit true
-- @see environment.states.datarenderer.DataRenderer
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local svg_renderer = require('arcades.utils.svg_renderer')
......@@ -7,24 +15,24 @@ assert(environment.states.datarenderer.DataRenderer)
local module = {}
local class, super = torch.class('GraphicalDataRenderer', "DataRenderer", module)
--- Attributes.
-- @section attributes
--- Data Types
-- @section data-types
--- `__init` argument.
-- @tfield string map_path Path to the base SVG path
-- @table InitArgument
--- Fields
-- @section fields
--- The table containing SVG data
-- @tfield number width Width of the image
-- @tfield number height Height of the image
-- @tfield table placeholders List of elements to complete at runtime
-- @tfield table placed_values List of values that will be inserted in place of placeholders in <code>str_data</code>
-- @tfield string str_data SVG string representation with Lua format placeholders (%s)
-- @table self.svg
-- @tfield utils.svg_renderer.svg_object self.svg
--- @section end
--- Default constructor
-- @tparam table args
-- @param[opt] args.logger Logger object to use
-- @tparam[opt=3] number args.tries Maximum number of attempts before the environment change its state
-- @see SmartHomeEnvironment:__init
-- @tparam InitArgument args
-- @mtodo Fix usage of `dump`
function class:__init(args)
args = args or {}
super.__init(self, args)
......@@ -39,13 +47,20 @@ function class:__init(args)
self.last_render = nil
end
--- Public Methods
-- @section public-methods
--- Return @{utils.placeholder|placeholders} of the underlying SVG.
-- @treturn table @{utils.svg_renderer.svg_object|self.svg.placeholders}
function class:get_placeholders()
return self.svg.placeholders
end
--- Overriden methods.
-- @section overriden
--- Apply given `state` to the image.
-- @tparam {[string]=integer,...} state Map of values for sensors
-- @treturn torch.Tensor/tensor.md/ Rendered image
-- @override true
-- @see DataRenderer:render
function class:render(state)
if state == nil then
for _, ph in pairs(self.svg.placeholders) do
......
--- A set of data rendering strategies.
--
-- Contains some classes to render data. Only concrete class for the moment
-- is one to generate an image from data.
--
-- List of classes:
--
-- * @{environment.states.datarenderer.DataRenderer|DataRenderer}
-- * @{environment.states.datarenderer.GraphicalDataRenderer|GraphicalDataRenderer}
--
-- @package environment.states.datarenderer
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
return require('arcades.utils.package_loader')(...)
--- Base abstract class from which inherit to implement any data
-- providing strategy.
-- @classmod environment.states.datasource.DataSource
-- @alias class
-- @inherit true
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local arcades = require('arcades')
......@@ -5,14 +13,35 @@ local arcades = require('arcades')
local module = {}
local class, super = torch.class('DataSource', 'ArcadesComponent', module)
--- Fields
-- @section fields
--- Current state.
-- @tfield {[string]=number,...} self.state
--- Terminal signal for current `state`.
-- @tfield boolean self.terminal
--- @section end
--- Default constructor.
-- @tparam ArcadesComponent.InitArgument args
-- @mtodo Fix usage of `dump`
function class:__init(args)
super.__init(self, args)
end
--- Public Methods
-- @section public-methods
--- Get the current state.
-- @treturn {[string]=number,...} Current state
function class:get_state()
return self.state or {}
end
--- Get the terminal signal of the current state.
-- @treturn boolean `self.terminal`
function class:is_terminal()
local t = self.terminal
if t == nil then
......@@ -21,10 +50,17 @@ function class:is_terminal()
return t
end
--- Return expected action for the current state.
-- @treturn table Expected action
-- @mtodo Use DP for polymorph actions.
function class:get_expected_action()
return self.expected_action or {'none', 'none'}
end
--- Abstract Methods
-- @section abstract-methods
--- Move to the next state.
function class:update()
error(
string.format(
......@@ -35,6 +71,7 @@ function class:update()
2)
end
--- Reset provider.
function class:reset()
error(
string.format(
......
--- A set of data providing strategies.
--
-- Contains some classes to provide data.
--
-- List of classes:
--
-- * @{environment.states.datasource.DataSource|DataSource}
--
-- List of sub-packages:
--
-- * @{environment.states.datasource.labelled|labelled}
-- * @{environment.states.datasource.simulated|simulated}
--
-- @mtodo Rename it to `dataprovider`
-- @package environment.states.datasource
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
return require('arcades.utils.package_loader')(...)
--- Base class from which inherit to implement a corpus based data
-- providing strategy.
-- @classmod environment.states.datasource.labelled.DataLabelled
-- @alias class
-- @inherit true
-- @see environment.states.datasource.DataSource
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local paths = require('paths')
......@@ -10,6 +19,22 @@ local environment = require('arcades.environment')
assert(environment.states.datasource.DataSource)
local class, super = torch.class('DataLabelled', "DataSource", module)
--- Data Types
-- @section data-types
--- `__init` argument.
-- @tfield environment.BaseEnvironment environment_model @{environment.BaseEnvironment|Environment} to which is linked this object
-- @tfield[opt=0.001] number input_time_scale Time scale of the corpus timestamps
-- @tfield[opt=1] number output_time_scale Time scale of the agent
-- @tfield[opt] number time_coef Coefficient used to translate data corpus to agent time scale
-- @tfield string data_path Path to the data corpus
-- @mtodo Don't mix with `dump`.
-- @table InitArgument
--- @section end
--- Default constructor.
-- @tparam InitArgument args
function class:__init(args)
super.__init(self, args)
self.environment_model = args.environment_model
......@@ -23,10 +48,20 @@ function class:__init(args)
self.last_data_index = 0
end
--- Public Methods
-- @section public-methods
--- Reset
-- @treturn `self`
function class:reset()
return self
end
--- Private Methods
-- @section private-methods
--- Build state from corpus
-- @tfield integer data_index Index of sample to load
function class:_update_state_with_values(data_index)
self.state = self.state or {}
for k, v in pairs(self.data[data_index].values) do
......@@ -39,6 +74,9 @@ function class:_update_state_with_values(data_index)
end
end
--- Fill state with values until timestamp.
-- @tparam integer timestamp Last value to use to fill the state
-- @tparam boolean from_current Fill from current state or start with a new one
function class:_fill_state(timestamp, from_current)
self.state = from_current and self.state or {}
self.last_data_index = from_current and self.last_data_index or 0
......@@ -52,10 +90,18 @@ function class:_fill_state(timestamp, from_current)
self.current_timestamp = timestamp
end
--- Compare timestamped data based on timestamp
-- @param i1 timestamped data 1
-- @param i2 timestamped data 2
-- @treturn boolean `i1 < i2`
function class._compare_timestamped_data(i1, i2)
return i1.timestamp < i2.timestamp
end
--- Merge to data corpora checking timestamps consistency.
-- @tparam table d1 First corpus
-- @tparam table d2 Second corpus
-- @treturn table Merged corpus
function class._merge_data(d1, d2)
local i, j = 1, 1
local result = {}
......@@ -95,6 +141,10 @@ function class._merge_data(d1, d2)
return result
end
--- Load a corpus from a csv file
-- @tparam string file_path Path to the CSV file
-- @tparam number time_coef Coefficent to apply to timestamp
-- @treturn table Loaded data
function class._load_csv_file(file_path, time_coef)
assert(paths.filep(file_path))
local data = {}
......@@ -122,7 +172,10 @@ function class._load_csv_file(file_path, time_coef)
return data
end
--- Load data from different CSV file in a directory
-- @tparam string dir_path Path to the directory
-- @tparam number time_coef Coefficent to apply to timestamp
-- @treturn table Loaded data
function class._load_data_dir(dir_path, time_coef)
assert(paths.dirp(dir_path))
local dir_data = {}
......@@ -136,6 +189,9 @@ function class._load_data_dir(dir_path, time_coef)
end
--- Parse plain text files to build a data table.
-- @tparam string data_path Path to the data
-- @tparam number time_coef Coefficent to apply to timestamp
-- @treturn table Loaded data
function class._parse_data(data_path, time_coef)
assert(data_path, "Path to data not given.")
assert(paths.dirp(data_path), string.format(
......
--- @{DataSource|Data providers} that generate data from labelled corpus.
--
-- List of classes:
--
-- * @{environment.states.datasource.labelled.DataLabelled|DataLabelled}
-- * @{environment.states.datasource.labelled.AnnotatedLabelledDataProvider|AnnotatedLabelledDataProvider}
-- * @{environment.states.datasource.labelled.RealTimeSensorDataLabelled|RealTimeSensorDataLabelled}
-- * @{environment.states.datasource.labelled.VocalBasedSensorDataLabelled|VocalBasedSensorDataLabelled}
--
-- @package environment.states.datasource.labelled
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
return require('arcades.utils.package_loader')(...)
--- Base class from which inherit to implement a simulated data
-- providing strategy.
-- @classmod environment.states.datasource.simulated.DataSimulated
-- @alias class
-- @inherit true
-- @see environment.states.datasource.DataSource
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local module = {}
......@@ -5,6 +14,11 @@ local environment = require('arcades.environment')
assert(environment.states.datasource.DataSource)
local class, _ = torch.class('DataSimulated', "DataSource", module)
--- Public Methods
-- @section public-methods
--- Reset the data provider
-- @return `self`
function class:reset()
return self
end
......
--- Class that generate inferred data.
-- @classmod environment.states.datasource.simulated.SweetHomeDataInferredSimulated
-- @alias class
-- @inherit true
-- @see environment.states.datasource.datasimulated.DataSimulated
-- @see environment.states.datasource.DataSource
-- @see ArcadesComponent
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local torch = require('torch')
local tablex = require('pl.tablex')
......@@ -9,6 +18,22 @@ local module = {}