org.powertac.common
Class Competition

java.lang.Object
  org.powertac.common.Competition

public class Competition
extends Object

A competition instance represents a single PowerTAC competition and at the same time serves as the place for all competition properties that can be adjusted during competition setup (i.e. during server runtime but before competition start). This is an immutable value type, and most parameters are included in the PluginConfig instances, rather than in individual fields. The single instance is communicated to brokers at the beginning of a game scenario.

Author:

Carsten Block, KIT; John Collins, U of Minnesota

Method Summary

Competition	addBroker(String brokerUsername) Adds a broker to the Competition.
Competition	addCustomer(CustomerInfo customer) Adds a customer to the Competition.
static Competition	currentCompetition() Returns the current Competition instance.
int	getBootstrapDiscardedTimeslots() Length of bootstrap interval in msec.
int	getBootstrapTimeslotCount() Number of timeslots in the bootstrap data report for a normal sim.
List<String>	getBrokers() The Brokers who are participating in this Competion.
Map<String,Long>	getClockParameters() Returns the clock parameters for the start of a normal sim session as a simple Map, to simplify code that must mediate between Competition and TimeService instances.
List<CustomerInfo>	getCustomers() The list of customers (or more precisely, customer models) in the simulation environment.
int	getDeactivateTimeslotsAhead() Number of timeslots, starting with the current timeslot, that are closed for trading.
String	getDescription() Uninterpreted text that further describes the competition.
int	getExpectedTimeslotCount() Expected value of timeslot count for a normal sim session.
long	getId()
int	getLatitude() Returns approximate latitude in degrees for sim locale.
int	getMinimumTimeslotCount() Minimum number of timeslots for this competition.
String	getName() Returns the competition name
org.joda.time.Instant	getSimulationBaseTime() Start time of a sim session in the sim world.
long	getSimulationModulo() Minimum value in milliseconds by which time advances in a simulation, or in other words, the size of a clock tick.
long	getSimulationRate() The time-compression factor for the simulation.
int	getSimulationTimeslotSeconds() Returns the number of seconds in wall-clock time per timeslot, truncated to an integer.
long	getTimeslotDuration() Returns the duration of a timeslot in milliseconds sim-time.
int	getTimeslotLength() Returns the length of a timeslot in minutes (sim time).
int	getTimeslotsOpen() Number of timeslots simultaneously open for trading.
int	getTimezoneOffset() Returns timezone offset for sim locale.
static Competition	newInstance(String name)
static void	setCurrent(Competition newCurrent) Makes a Competition instance be the "current" competition - this is needed in a broker when the Competition instance arrives from the server.
String	toString()
void	update(Competition template) Updates selected fields of this Competition from a template.
Competition	withBootstrapDiscardedTimeslots(int count) Fluent setter for bootstrap interval.
Competition	withBootstrapTimeslotCount(int bootstrapTimeslotCount) Fluent setter for the bootstrap timeslot count.
Competition	withDeactivateTimeslotsAhead(int deactivateTimeslotsAhead) Fluent setter for number of timeslots, starting with the current timeslot, that are closed for trading.Default value is 1.
Competition	withDescription(String description) Fluent setter for competition description.
Competition	withExpectedTimeslotCount(int expectedTimeslotCount) Fluent setter for the expected length of a normal sim session.
Competition	withLatitude(int latitude) Fluent setter for latitude value
Competition	withMinimumTimeslotCount(int minimumTimeslotCount) Fluent setter for minimumTimeslotCount.
Competition	withSimulationBaseTime(org.joda.time.Instant simulationBaseTime) Fluent setter for simulation base time.
Competition	withSimulationBaseTime(long baseTime) Fluent setter for simulation base time that takes a long.
Competition	withSimulationBaseTime(String baseTime) Fluent setter for simulation base time that takes a String, interpreted as a standard DateTimeFormat as yyy-MM-dd.
Competition	withSimulationModulo(long simulationModulo) Fluent setter for simulation modulo.
Competition	withSimulationRate(long simulationRate) Fluent setter for time compression ratio.
Competition	withSimulationTimeslotSeconds(int seconds) Fluent setter for controlling simulation rate by setting the number of wall-clock seconds per timeslot.
Competition	withTimeslotLength(int timeslotLength) Fluent setter for timeslot length, interpreted as minutes in sim time.
Competition	withTimeslotsOpen(int timeslotsOpen) Fluent setter for the open timeslot count.
Competition	withTimezoneOffset(int offset) Fluent setter for timezone offset

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

newInstance

public static Competition newInstance(String name)

currentCompetition

public static Competition currentCompetition()

Returns the current Competition instance. There should always be either zero or one of these.

setCurrent

public static void setCurrent(Competition newCurrent)

Makes a Competition instance be the "current" competition - this is needed in a broker when the Competition instance arrives from the server.

getId

public long getId()

getName

public String getName()

Returns the competition name

getDescription

public String getDescription()

Uninterpreted text that further describes the competition.

withDescription

@ConfigurableValue(description="user-readable description of the Competition",
                   valueType="String")
public Competition withDescription(String description)

Fluent setter for competition description.

getTimeslotLength

public int getTimeslotLength()

Returns the length of a timeslot in minutes (sim time).

getTimeslotDuration

public long getTimeslotDuration()

Returns the duration of a timeslot in milliseconds sim-time.

withTimeslotLength

@ConfigurableValue(name="timeslotLength",
                   description="length of timeslot in minutes sim time",
                   valueType="Integer")
public Competition withTimeslotLength(int timeslotLength)

Fluent setter for timeslot length, interpreted as minutes in sim time.

getMinimumTimeslotCount

public int getMinimumTimeslotCount()

Minimum number of timeslots for this competition. The actual number is randomized by CompetitionControl at sim start time.

withMinimumTimeslotCount

@ConfigurableValue(valueType="Integer",
                   description="minimum number of timeslots in simulation run")
public Competition withMinimumTimeslotCount(int minimumTimeslotCount)

Fluent setter for minimumTimeslotCount.

getExpectedTimeslotCount

public int getExpectedTimeslotCount()

Expected value of timeslot count for a normal sim session.

withExpectedTimeslotCount

@ConfigurableValue(valueType="Integer",
                   description="expected number of timeslots in simulation run")
public Competition withExpectedTimeslotCount(int expectedTimeslotCount)

Fluent setter for the expected length of a normal sim session.

getTimeslotsOpen

public int getTimeslotsOpen()

Number of timeslots simultaneously open for trading.

withTimeslotsOpen

@ConfigurableValue(valueType="Integer",
                   description="expected number of timeslots in simulation run")
public Competition withTimeslotsOpen(int timeslotsOpen)

Fluent setter for the open timeslot count. Default value is 24.

getDeactivateTimeslotsAhead

public int getDeactivateTimeslotsAhead()

Number of timeslots, starting with the current timeslot, that are closed for trading.

withDeactivateTimeslotsAhead

@ConfigurableValue(valueType="Integer",
                   description="expected number of timeslots in simulation run")
public Competition withDeactivateTimeslotsAhead(int deactivateTimeslotsAhead)

Fluent setter for number of timeslots, starting with the current timeslot, that are closed for trading.Default value is 1.

getSimulationBaseTime

public org.joda.time.Instant getSimulationBaseTime()

Start time of a sim session in the sim world. This is actually the start of the bootstrap session, which is typically 15 days before the start of a normal sim session.

withSimulationBaseTime

public Competition withSimulationBaseTime(org.joda.time.Instant simulationBaseTime)

Fluent setter for simulation base time. This is the start of a simulation scenario, in the sim world, at the beginning of a bootstrap session. So if the bootstrap session collects data for 14 days, with an addional day of discarded data at the beginning, it is 15 days before the start of a normal sim.

withSimulationBaseTime

@ConfigurableValue(valueType="String",
                   description="Scenario start time of the bootstrap portion of a simulation")
public Competition withSimulationBaseTime(String baseTime)

Fluent setter for simulation base time that takes a String, interpreted as a standard DateTimeFormat as yyy-MM-dd.

withSimulationBaseTime

public Competition withSimulationBaseTime(long baseTime)

Fluent setter for simulation base time that takes a long.

getTimezoneOffset

public int getTimezoneOffset()

Returns timezone offset for sim locale.

withTimezoneOffset

@ConfigurableValue(valueType="Integer",
                   description="Timezone offset from UTC for sim locale")
public Competition withTimezoneOffset(int offset)

Fluent setter for timezone offset

getLatitude

public int getLatitude()

Returns approximate latitude in degrees for sim locale.

withLatitude

@ConfigurableValue(valueType="Integer",
                   description="Approximate latitude of sim locale")
public Competition withLatitude(int latitude)

Fluent setter for latitude value

getBootstrapTimeslotCount

public int getBootstrapTimeslotCount()

Number of timeslots in the bootstrap data report for a normal sim.

withBootstrapTimeslotCount

@ConfigurableValue(valueType="Integer",
                   description="Number of timeslots in bootstrap session during which data is collected")
public Competition withBootstrapTimeslotCount(int bootstrapTimeslotCount)

Fluent setter for the bootstrap timeslot count. It only makes sense to change this before running a bootstrap session.

getBootstrapDiscardedTimeslots

public int getBootstrapDiscardedTimeslots()

Length of bootstrap interval in msec. Add this to the simulation base time, and you get the start time for a normal sim session.

withBootstrapDiscardedTimeslots

@ConfigurableValue(valueType="Integer",
                   description="Number of timeslots in bootstrap session that are discardedbefore data collection begins")
public Competition withBootstrapDiscardedTimeslots(int count)

Fluent setter for bootstrap interval.

getSimulationRate

public long getSimulationRate()

The time-compression factor for the simulation.

withSimulationRate

@ConfigurableValue(valueType="Integer",
                   description="Time compression ratio for simulation clock")
public Competition withSimulationRate(long simulationRate)

Fluent setter for time compression ratio. Default value is 720, which runs 1-hour timeslots in 5 real-time seconds.

getSimulationTimeslotSeconds

public int getSimulationTimeslotSeconds()

Returns the number of seconds in wall-clock time per timeslot, truncated to an integer.

withSimulationTimeslotSeconds

@ConfigurableValue(valueType="Integer",
                   description="Time compression ratio for simulation clock")
public Competition withSimulationTimeslotSeconds(int seconds)

Fluent setter for controlling simulation rate by setting the number of wall-clock seconds per timeslot. Only integer values are allowed. Results may be strange if timeslotLength is changed after this is set.

getSimulationModulo

public long getSimulationModulo()

Minimum value in milliseconds by which time advances in a simulation, or in other words, the size of a clock tick. Normally it's one timeslot. In the sim world, time is always at the beginning of a clock tick.

withSimulationModulo

@ConfigurableValue(valueType="Long",
                   description="Size, in milliseconds, of a simulation clock tick.Normally, this is the same as a timeslot.")
public Competition withSimulationModulo(long simulationModulo)

Fluent setter for simulation modulo. Most likely, most server components will not respond properly for values that are different from a timeslot length. Default value is 3600000 msec.

getClockParameters

public Map<String,Long> getClockParameters()

Returns the clock parameters for the start of a normal sim session as a simple Map, to simplify code that must mediate between Competition and TimeService instances. The computed base time will be the base time of the bootstrap period plus the length of the bootstrap period.

getBrokers

public List<String> getBrokers()

The Brokers who are participating in this Competion.

addBroker

public Competition addBroker(String brokerUsername)

Adds a broker to the Competition. This only makes sense in the server environment.

getCustomers

public List<CustomerInfo> getCustomers()

The list of customers (or more precisely, customer models) in the simulation environment.

addCustomer

public Competition addCustomer(CustomerInfo customer)

Adds a customer to the Competition. This only makes sense in the server environment.

update

public void update(Competition template)

Updates selected fields of this Competition from a template. This is designed to be used to copy attributes from a bootstrap run into a normal sim run.

toString

public String toString()

Overrides:

toString in class Object