simulations

Documentation

Index

• Variables
• type CreateSimulationInput
• type Error
• type GroupID
  • func (gid GroupID) String() string
• type Kind
• type Marsupial
  • func NewMarsupial(parent, child Robot) Marsupial
• type Robot
• type Service
• type Simulation
• type Statistics
• type Status
• type Summary

Variables

var (
	// ErrInvalidGroupID is returned when a group id is invalid.
	ErrInvalidGroupID = errors.New("invalid group id")

	// ErrIncorrectStatus is returned when a simulation status is not correct at the time it's being checked.
	ErrIncorrectStatus = errors.New("incorrect status")

	// ErrIncorrectKind is returned when a simulation kind is not correct at the time it's being checked.
	ErrIncorrectKind = errors.New("incorrect kind")

	// ErrSimulationWithError is returned when a simulation has an error.
	ErrSimulationWithError = errors.New("simulation with error")

	// ErrSimulationProcessed is returned when simulation is trying to be processed twice.
	ErrSimulationProcessed = errors.New("simulation has been processed")

	// ErrSimulationPlatformNotDefined is returned when a Simulation does not have a Platform defined.
	ErrSimulationPlatformNotDefined = errors.New("simulation has no platform defined")
)

Types

type CreateSimulationInput

type CreateSimulationInput struct {
	Name      string
	Owner     *string
	Creator   string
	Image     []string
	Private   bool
	StopOnEnd bool
	Extra     string
	Track     string
	Robots    string
}

CreateSimulationInput contains all the information needed to create a simulation.

type Error

type Error string

Error is used to assign an error to a simulation. Simulations with errors are forbidden to run.

type GroupID

type GroupID string

GroupID is an universally unique identifier that identifies a Simulation.

func (GroupID) String

func (gid GroupID) String() string

String returns the string representation of a GroupID.

type Kind

type Kind uint

Kind is used to identify if a Simulation is a single simulation or a multisim. If a simulation is a multisim, different Kind values are used to identify if the simulations is a parent simulation or a child simulation.

var (
	// SimSingle represents a single simulation.
	SimSingle Kind = 0
	// SimParent represents a parent simulation.
	SimParent Kind = 1
	// SimChild represents a child simulation.
	SimChild Kind = 2
)

type Marsupial

type Marsupial interface {
	// GetParent returns the marsupial parent robot.
	GetParent() Robot
	// GetChild returns the marsupial child robot.
	GetChild() Robot
}

Marsupial is a combination of robots.

func NewMarsupial

func NewMarsupial(parent, child Robot) Marsupial

NewMarsupial initializes a new Marsupial from the given pair of parent and child robots.

type Robot

type Robot interface {
	// GetName returns the robot's name. It's usually provided by the user.
	GetName() string
	// GetKind returns the robot's type. It's the robot config type.
	GetKind() string
	// GetImage returns the robot's image. It will be used as the robot brain.
	GetImage() string
	// IsEqual returns true if the given robot is the same robot.
	IsEqual(Robot) bool
}

Robot represents a generic robot used in a Simulation.

type Service

type Service interface {
	Create(input CreateSimulationInput) (Simulation, error)

	// Get returns a simulation with the given GroupID.
	Get(groupID GroupID) (Simulation, error)

	// GetParent returns the child simulation's parent with the given GroupID.
	GetParent(groupID GroupID) (Simulation, error)

	// UpdateStatus updates the simulation status with the given groupID.
	UpdateStatus(groupID GroupID, status Status) error

	// UpdateScore updates the simulation score.
	UpdateScore(groupID GroupID, score *float64) error

	// Update updates the simulation matching the given groupID with the given simulation data.
	Update(groupID GroupID, simulation Simulation) error

	// GetRobots returns the robot list of the simulation with the given GroupID.
	GetRobots(groupID GroupID) ([]Robot, error)

	// MarkStopped marks a simulation identified with the given Group ID as stopped.
	MarkStopped(groupID GroupID) error

	// MarkCharged marks a simulation identified with the given Group ID as charged.
	MarkCharged(groupID GroupID) error

	// GetWebsocketToken returns a websocket token for a certain simulation with the given GroupID.
	GetWebsocketToken(groupID GroupID) (string, error)
}

Service is a generic simulation service interface.

type Simulation

type Simulation interface {
	// GetGroupID returns the current Simulation's group id.
	GetGroupID() GroupID

	// GetStatus returns the current Simulation's status.
	GetStatus() Status

	// HasStatus checks if the current Simulation has a given status.
	HasStatus(status Status) bool

	// SetStatus sets a given status to the Simulation.
	SetStatus(status Status)

	// GetKind returns the current simulation's kind.
	GetKind() Kind

	// IsKind checks if the current Simulation is of the given kind.
	IsKind(Kind) bool

	// GetError returns the current simulation's error. It returns nil if the simulation doesn't have an error.
	GetError() *Error

	// GetImage returns the simulation's docker image. This image is used as the solution image.
	GetImage() string

	// GetLaunchedAt returns the time and date the simulation was officially launched. This date can differ from the
	// time the simulation was requested due to the simulation having been held, or because it has been unable to
	// launch because of insufficient cloud resources.
	GetLaunchedAt() *time.Time

	// GetValidFor returns the amount of time that the simulation is considered valid.
	GetValidFor() time.Duration

	// IsProcessed returns true if the Simulation has been already processed.
	IsProcessed() bool

	// GetOwner returns the Simulation's owner.
	GetOwner() *string

	// GetCreator returns the Simulation's creator.
	GetCreator() string

	// GetPlatform returns the Simulation's platform.
	GetPlatform() *string

	// SetRate sets the given rate to this simulation.
	SetRate(rate calculator.Rate)

	// GetRate returns the rate at which this simulation should be charged.
	GetRate() calculator.Rate

	// GetStoppedAt returns the date and time when a simulation stopped from running.
	GetStoppedAt() *time.Time

	// GetCost applies the current rate to this simulation resulting in the amount of money that it should be charged.
	GetCost() (uint, calculator.Rate, error)

	// GetChargedAt returns the time and date this simulation was charged.
	GetChargedAt() *time.Time
}

Simulation groups a set of methods to identify a simulation.

type Statistics

type Statistics struct {
	// Started is true if the simulation was started.
	Started int `yaml:"was_started"`
	// SimulationTime is the duration in seconds of the simulation time.
	SimulationTime int `yaml:"sim_time_duration_sec"`
	// RealTime is the real duration in seconds of the simulation.
	RealTime int `yaml:"real_time_duration_sec"`
	// ModelCount is the amount of models used in the simulation.
	ModelCount int `yaml:"model_count"`
}

Statistics contains the summary values of a simulation run.

type Status

type Status string

Status represents a stage a Simulation can be in.

var (
	// StatusPending is used when a simulation is pending to be scheduled.
	StatusPending Status = "pending"

	// StatusRunning is used when a simulation is running.
	StatusRunning Status = "running"

	// StatusRejected is used when a simulation has been rejected.
	StatusRejected Status = "rejected"

	// StatusLaunchingInstances is used when a simulation has entered the launching instances phase.
	StatusLaunchingInstances Status = "launching-instances"

	// StatusLaunchingPods is used when a simulation has entered the launching pods phase.
	StatusLaunchingPods Status = "launching-pods"

	// StatusWaitingInstances is used when a simulation is waiting for instances to be launched.
	StatusWaitingInstances Status = "waiting-instances"

	// StatusWaitingNodes is used when a simulation is waiting for nodes to be ready
	StatusWaitingNodes Status = "waiting-nodes"

	// StatusWaitingPods is used when a simulation is waiting for pods to be ready.
	StatusWaitingPods Status = "waiting-pods"

	// StatusTerminateRequested is used when a simulation has been scheduled to be terminated.
	StatusTerminateRequested Status = "terminate-requested"

	// StatusDeletingPods is used when the pods of a certain simulation are being deleted.
	StatusDeletingPods Status = "deleting-pods"

	// StatusDeletingNodes is used when the nodes of a certain simulation are being deleted.
	StatusDeletingNodes Status = "deleting-nodes"

	// StatusProcessingResults is used when a simulation's score and stats are being extracted from a gazebo server.
	StatusProcessingResults Status = "processing-results"

	// StatusTerminatingInstances is used when simulation instances are being deleted.
	StatusTerminatingInstances Status = "terminating-instances"

	// StatusTerminated is used when a simulation has been terminated.
	StatusTerminated Status = "terminated"

	// StatusSuperseded is used when a simulation has been superseded.
	StatusSuperseded Status = "superseded"

	// StatusRestarted is used when a simulation has been restarted.
	StatusRestarted Status = "restarted"

	// StatusUnknown is used to represent an unknown status.
	StatusUnknown Status = "unknown"
)

type Summary

type Summary struct {
	gorm.Model
	// GroupID identifies a simulation.
	GroupID *GroupID `json:"-" gorm:"not null;unique"`
	// Score is the simulation score.
	Score *float64 `json:"-"`
	// SimTimeDurationAvg is the average value of the simulation time duration.
	SimTimeDurationAvg float64 `json:"sim_time_duration_avg"`
	// SimTimeDurationStdDev is the standard deviation value of the simulation time duration. Only used by simulations.SimParent.
	SimTimeDurationStdDev float64 `json:"sim_time_duration_std_dev" gorm:"-"`
	// RealTimeDurationAvg is the average value of the real time duration.
	RealTimeDurationAvg float64 `json:"real_time_duration_avg"`
	// RealTimeDurationStdDev is the standard deviation value of the real time duration. Only used by simulations.SimParent.
	RealTimeDurationStdDev float64 `json:"real_time_duration_std_dev" gorm:"-"`
	// ModelCountAvg is the average value of the model count.
	ModelCountAvg float64 `json:"model_count_avg"`
	// ModelCountStdDev is the standard deviation value of the model count. Only used by simulations.SimParent.
	ModelCountStdDev float64 `json:"model_count_std_dev" gorm:"-"`
	// Sources stores the group ids of the children used to generate this summary. Only used by simulations.SimParent.
	Sources string `json:"-"`
	// RunData contains specific simulation run information. It should only be passed for single sims.
	RunData string `json:"-" gorm:"-"`
}

Summary contains the total score and average statistics for a certain simulation or group of simulations.