Commit a7c34cfe authored by Jason Rhinelander's avatar Jason Rhinelander

Added missing method/field documentation

This silences all the remaining doxygen warnings about undocumented
items.
parent 36079752
......@@ -90,6 +90,7 @@ class Firm : public agent::AssetAgent {
* already been transferred or released.
*/
class non_pending_exception : public std::exception {
/// Overridden to return a default "what" message for the exception
public: const char* what() const noexcept override { return "Attempt to transfer/release a non-pending firm Reservation"; }
};
};
......@@ -116,6 +117,7 @@ class Firm : public agent::AssetAgent {
*/
class supply_failure : public std::runtime_error {
public:
/// Exception constructor: takes an error message
supply_failure(std::string what);
};
/** Exception class indicating that the firm does not supply one of more of the goods in the
......@@ -124,7 +126,9 @@ class Firm : public agent::AssetAgent {
*/
class supply_mismatch : public supply_failure {
public:
/// Exception constructor: takes an error message
supply_mismatch(std::string what);
/// Exception constructor, default error message
supply_mismatch();
};
/** Exception class thrown when supplying the requested bundle would exceeds the firm's
......@@ -151,6 +155,11 @@ class Firm : public agent::AssetAgent {
*/
production_unavailable();
};
/** Exception class thrown when a firm is requested to produce an amount from production
* reserves greater than the amount that has actually been reserved.
*
* \sa produceReserved
*/
class production_unreserved : public supply_failure {
public:
/// Constructs the exception with the specified message
......
......@@ -131,10 +131,12 @@ class Market : public Member {
* already been bought or released.
*/
class non_pending_exception : public std::exception {
/// Overrides what() with an appropriate exception message
public: const char* what() const noexcept override { return "Attempt to buy/release a non-pending market Reservation"; }
};
};
/// Market::Reservation is a unique pointer to the private constructor Reservation_ class.
typedef std::unique_ptr<Reservation_> Reservation;
/** Returns the price information for buying the given multiple of the output bundle.
......@@ -282,18 +284,21 @@ class Market : public Member {
* requested.
*/
class output_infeasible : public std::exception {
/// Overrides what() with an appropriate exception message
public: const char* what() const noexcept override { return "Requested output not available"; }
};
/** Exception class throw when the market price required exceeds the maximum price
* specified.
*/
class low_price : public std::exception {
/// Overrides what() with an appropriate exception message
public: const char* what() const noexcept override { return "Requested output not available for given price"; }
};
/** Exception class thrown when the buyer's assets are not sufficient to purchase the
* requested output.
*/
class insufficient_assets : public std::exception {
/// Overrides what() with an appropriate exception message
public: const char* what() const noexcept override { return "Assets insufficient for purchasing requested output"; }
};
......
......@@ -459,7 +459,7 @@ class Member : private noncopyable {
* Simulation.
*/
void simulation(const std::shared_ptr<Simulation> &sim, const eris_id_t &id);
friend eris::Simulation;
friend class eris::Simulation;
/** Virtual method called just after the member is added to a Simulation object. The
* default implementation does nothing. This method is typically used to record a
......
......@@ -87,8 +87,8 @@ class Position final {
*/
double& operator[](int d);
/* Accesses the Position's `d`th coordinate, with `d=0` is the first
* dimension, with bounds checking.
/** Accesses the Position's `d`th coordinate, with `d=0` is the first dimension, with bounds
* checking.
*
* \throws std::out_of_range exception for `d >= dimensions`.
*/
......
......@@ -28,7 +28,7 @@ class Random final {
* mt19937_64 rng, which offers a good balance of randomness and performance.
*
* The returned rng is suitable for passing into a distribution, such as those provided in
* <random>.
* \<random\>.
*
* Example:
*
......
......@@ -35,7 +35,7 @@ namespace eris {
* set. Despite being in a vector, these values should really be treated as a set. Values
* will be in the same order as encountered in the input iterator.
*
* \param T the underlying data type template parameter is required, unfortunately. This shouldn't
* \tparam T the underlying data type template parameter is required, unfortunately. This shouldn't
* be necessary at all, since it is obtainable from the class of the given iterator, but gcc
* (as of 4.8.1) chokes on that, hence the additional (required) template parameter.
*/
......@@ -91,8 +91,11 @@ all_combinations(
template <class Iter>
class range_ final : public std::pair<Iter, Iter> {
public:
/// Builds an iteratable range from a start and end iterator
range_(std::pair<Iter, Iter> const &pair) : std::pair<Iter, Iter>(pair) {}
/// Returns the beginning of the range
Iter begin() const { return this->first; }
/// Returns the end of the range
Iter end() const { return this->second; }
};
/** Takes a std::pair of iterators that represents a range, and returns an iterable object for that
......@@ -116,10 +119,15 @@ range_<Iter> range(std::pair<Iter, Iter> const &pair) {
*/
class Stepper final {
public:
/// The default (possibly relative) initial step
static constexpr double default_initial_step = 1.0/32.0;
/// The default number of same-direction steps before the step size is increased
static constexpr int default_increase_count = 4;
/// The smallest (possibly relative) step that will be taken
static constexpr double default_min_step = std::numeric_limits<double>::epsilon();
/// The largest (possibly relative) step that will be taken
static constexpr double default_max_step = 0.5;
/// The default value for whether steps are relative (true) or absolute (false)
static constexpr bool default_relative_steps = true;
/** Constructs a new Stepper object.
......
This diff is collapsed.
......@@ -53,8 +53,14 @@ class PriceFirm : public Firm, public virtual interopt::Advance {
virtual void interAdvance() override;
protected:
Bundle price_, output_;
double capacity_, capacity_used_ = 0;
/// The base price bundle; the firm accepts multiples of this bundle as payment
Bundle price_;
/// The output bundle: the firm produces multiples of this bundle as output
Bundle output_;
/// The per-period capacity of the firm. May be infinity.
double capacity_;
/// The capacity of the firm already used up in the current period.
double capacity_used_ = 0;
/** Returns the multiple, potentially infinity, of Bundle b that this firm is able to
* produce before hitting its capacity constraint. Returns 0 if the firm has already hit
......
......@@ -18,7 +18,7 @@ class QFirm : public FirmNoProd, public virtual interopt::Advance, public virtua
*
* \param out the Bundle of output the firm produces multiples of.
*
* \param initial_quantity the quantity to produce at the beginning of the next period. For
* \param initial_capacity the quantity to produce at the beginning of the next period. For
* future periods this value will typically be adjusted (by QFStepper or similar) upwards or
* downwards depending on the previous period's results and change in market price.
*
......
......@@ -72,6 +72,10 @@ class InterStepper : public Member, public virtual OptApply {
* \param stepper Stepper object controlling the steps.
*
* \param period same as in InterStepper(double, int, int) constructor.
*
* \param period_offset when `period > 1` this value controls which simulation periods are
* considered for taking steps. For example, if `period=5` then `period_offset=2` means
* steps should be taken in periods 2, 7, 12, etc.
*/
InterStepper(Stepper stepper, int period = default_period, int period_offset = default_period_offset);
......
......@@ -22,6 +22,10 @@ class PriceStepper : public ProfitStepper {
* \param firm the PriceFirm object (or subclass thereof) that this optimizer works on. The
* PriceFirm must already have an initial price set.
*
* \param step the initial step size
*
* \param increase_count the number of steps in the same direction required before the step
* size is increased.
*/
PriceStepper(
const PriceFirm &firm,
......
......@@ -91,6 +91,10 @@ class IncrementalBuyer : public Member, public virtual OptApplyReset {
/** If enabled, in addition to the most preferred (as interpreted using the permuteThreshold() or
* permuteAll() values) markets, permutations involving markets with a utility change of 0
* will be considered, even when there are positive utility options.
*
* This is needed when utility is multiplicative, for example, \f$u = xyz\f$ in which
* positive amounts of each of x, y, and z are required before increments in any result in
* utility gains.
*/
void permuteZeros(const bool &pz) noexcept;
......@@ -109,15 +113,33 @@ class IncrementalBuyer : public Member, public virtual OptApplyReset {
virtual void intraReset() override;
protected:
/// The id of the consumer this optimizer controls
const eris_id_t con_id;
/// The id of the money good in the simulation
const eris_id_t money;
/// A bundle consisting of example 1 of the money good
const Bundle money_unit;
/** The number of rounds to use to use to spend income. Each round spends (on average)
* `1/rounds` of initial income.
*/
const int rounds = 100;
/// The current round from 0 to `rounds`.
int round = -1;
/// The permutation threshold value. \sa permuteThreshold()
double threshold = 1.0 - 1e-8;
/** Whether to include goods that individually yield zero utility gain in the considered
* good permutations. \sa permuteZeros()
*/
bool permute_zeros = false;
/** Market reservations for the goods the agent has decided to buy. These are established
* during intraOptimize(), completed during intraApply(), and cancelled in intraReset().
*/
std::forward_list<Market::Reservation> reservations;
/** Declares a dependency on the consumer and the money good when added to a simulation so
* that removing either the consumer or the money good from the simulation will
* automatically remove this optimizer.
*/
virtual void added() override;
/** Performance one step of optimization, reserving (approximately) 1/rounds of income each
......
......@@ -26,6 +26,8 @@ class MUPD : public Member, public virtual OptApplyReset {
/** Constructors a MUPD optimizer given a differentiable consumer instance and a money good.
*
* \param consumer the consumer this MUPD optimizer controls
* \param money the money good that the consumer spends
* \param tolerance the relative tolerance of the algorithm; optimization will stop when the
* difference between highest and lowest MU/$ values (calculated as \f$ \frac{highest -
* lowest}{highest} \f$ is smaller than this value. Defaults to 1.0e-10.
......@@ -53,14 +55,21 @@ class MUPD : public Member, public virtual OptApplyReset {
*/
class market_exhausted_error : public std::runtime_error {
public:
/** Constructor sets an appropriate `what()` message and stores the given market id
* in `market`.
*/
market_exhausted_error(eris_id_t mkt) : std::runtime_error("Cannot computed MU/$ in exhausted market"), market(mkt) {}
/// The id of the exhausted market that caused this exception to occur
const eris_id_t market;
};
protected:
/// The id of the consumer this optimizer applies to
const eris_id_t con_id;
/// The id of the money good that the consumer spends
const eris_id_t money;
/// A fixed bundle of exactly 1 unit of the money good
const Bundle money_unit;
/** Stores the quantity allocation information for a particularly spending allocation.
......@@ -82,10 +91,10 @@ class MUPD : public Member, public virtual OptApplyReset {
allocation spending_allocation(const std::unordered_map<eris_id_t, double> &spending) const;
/** Calculates the marginal utility per money unit evaluated at the given Bundle.
* \param con the shared consumer object
* \param an active write lock on the consumer
* \param mkt_id the market id for which to calculate
* \param a the allocation as returned by spending_allocation
* \param con the consumer
* \param lock an already-active write lock on the consumer
* \param mkt_id the market id for which to calculate MU/$
* \param a the allocation as returned by spending_allocation()
* \param b the Bundle at which to evaluate marginal utility
*
* Note that this method is not, by itself, thread-safe: calling code should have already
......
......@@ -42,12 +42,21 @@ class Bertrand : public Market {
virtual void addFirm(SharedMember<Firm> f) override;
protected:
/** Whether to randomize when multiple firms offer the good at exactly the same (lowest)
* price. If true, a random firm supplies the good; if false, the spending is divided
* equally between lowest-price firms.
*/
bool randomize;
/** Stores a quantity and a total price that quantity is sold for. */
struct share { double q, p; };
struct share {
double q; ///< The total quantity supplied by a firm
double p; ///< The total price to be paid to the firm for the quantity `q`
};
/** Allocation information. */
struct allocation {
/// The Market::price_info associated with the allocation
price_info p;
/// A map of firm id to the quantity/total price `share` value of that firm
std::unordered_map<eris_id_t, share> shares;
};
/** Calculates the allocations across firms for a purchase of q units of the good.
......
......@@ -143,7 +143,14 @@ class QMarket : public Market,
double price_;
/// The number of times we adjust price each period
unsigned int tries_, tries_first_;
unsigned int tries_;
/** The number of times to adjust price in the *first* period. This is usually considerably
* larger than `tries_` so as to be allowed to break free of the given initial value.
* Fewer tries for subsequent adjustments is justified on the grounds that variation from
* one period to the next is likely much smaller than variation from exogenous initial
* parameter to first period value.
*/
unsigned int tries_first_;
/// The number of times we have already tried to adjust in the current period
unsigned int tried_ = 0;
/// The excess capacity we found in the previous iteration
......
......@@ -3,12 +3,22 @@
namespace eris {
/** Simple utility class intended to be inherited (privately) for a class that should not be copied.
* This class has protected constructors and destructors which are not accessible to non-derived
* classes.
*
* Typical use:
*
* class MyClass : private eris::noncopyable { ... }
*/
class noncopyable {
protected:
/// Default empty constructor
noncopyable() = default;
/// Default Protected destructor
~noncopyable() = default;
/// Deleted copy constructor
noncopyable(const noncopyable&) = delete;
/// Deleted copy assignment operator
noncopyable& operator=(const noncopyable&) = delete;
};
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment