Package org.powertac.common

Class Competition

  • @Domain
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.
    Author:
    Carsten Block, KIT; John Collins, U of Minnesota

    • Method Detail

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

      • getPomId

        public String getPomId()
        Returns the pom version id from the server on which this Competition was created.

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

      • getMinimumTimeslotCount

        public int getMinimumTimeslotCount()
        Minimum number of timeslots for this competition. The actual number is randomized by CompetitionControl at sim start time.

      • getExpectedTimeslotCount

        public int getExpectedTimeslotCount()
        Expected value of timeslot count for a normal sim session.

      • getFixedTimeslotCount

        public Integer getFixedTimeslotCount()
        Fixed value for timeslot count, allows external tools such as tournament scheduler to compute game lengths externally.

      • getTimeslotsOpen

        public int getTimeslotsOpen()
        Number of timeslots simultaneously open for trading.

      • 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")
@StateChange
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.

      • getMinimumOrderQuantity

        public double getMinimumOrderQuantity()
        Minimum order quantity in MWh.

      • getMaxUpRegulationPaymentRatio

        public double getMaxUpRegulationPaymentRatio()
        Customers assume up-regulation will never clear if the regulation price is higher than the consumption price times this ratio, and so up-regulation will be ignored during tariff evaluation.

      • withMaxUpRegulationPaymentRatio

        @ConfigurableValue(valueType="Double",
                   description="Limit on up-regulation payment ratio")
public Competition withMaxUpRegulationPaymentRatio​(double value)
        Fluent setter for the maximum ratio between consumption price and up-regulation price for which customers will include up-regulation in tariff evaluation.

      • getUpRegulationDiscount

        public double getUpRegulationDiscount()
        Discount rate for overpriced up-regulation.

      • getMaxDownRegulationPaymentRatio

        public double getMaxDownRegulationPaymentRatio()
        If a tariff offers a down-regulation price larger (more negative) than the consumption price times this ratio, customers will not offer down-regulation, and will ignore down-regulation during tariff evaluation.

      • withMaxDownRegulationPaymentRatio

        @ConfigurableValue(valueType="Double",
                   description="Limit on down-regulation payment")
public Competition withMaxDownRegulationPaymentRatio​(double value)
        Fluent setter for the maximum down-regulation payment ratio.

      • getDownRegulationDiscount

        public double getDownRegulationDiscount()
        Discount rate for overpriced down-regulation.

      • withDownRegulationDiscount

        @ConfigurableValue(valueType="Double",
                   description="Discount rate on overpriced down-regulation")
public Competition withDownRegulationDiscount​(double value)
        Fluent setter for overpriced down-regulation discount rate.

      • getMarketBootstrapData

        public MarketBootstrapData getMarketBootstrapData()
        Getter and setter for market bootstrap data

      • getEstimatedConsumptionPremium

        public double getEstimatedConsumptionPremium()
        Brokers typically pay less for production than they charge for consumption. This ratio is an estimate of that margin that is used to modify the constraints on up- and down-regulation behavior.

      • withEstimatedConsumptionPremium

        @ConfigurableValue(valueType="Double",
                   description="Estimated ratio of consumption prices over production prices")
public Competition withEstimatedConsumptionPremium​(double value)
        Fluent setter for the estimated consumption price premium.

      • 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

        @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 yyyy-MM-dd. If that fails, try to parse the string as a regular (long) timestamp.

      • 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

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

      • getLatitude

        public int getLatitude()
        Returns approximate latitude in degrees for sim locale.

      • 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")
@StateChange
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.

      • getSimulationRate

        public long getSimulationRate()
        The time-compression factor for the simulation.

      • withSimulationRate

        @ConfigurableValue(valueType="Integer",
                   description="Time compression ratio for simulation clock")
@StateChange
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.")
@StateChange
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

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

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