chiark / gitweb /
Docs correct for new expected losses box
[ypp-sc-tools.db-test.git] / yarrg / web / docs
1 <%doc>
2
3  This is part of the YARRG website.  YARRG is a tool and website
4  for assisting players of Yohoho Puzzle Pirates.
5
6  Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
7  Copyright (C) 2009 Clare Boothby
8
9   YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
10   The YARRG website is covered by the GNU Affero GPL v3 or later, which
11    basically means that every installation of the website will let you
12    download the source.
13
14  This program is free software: you can redistribute it and/or modify
15  it under the terms of the GNU Affero General Public License as
16  published by the Free Software Foundation, either version 3 of the
17  License, or (at your option) any later version.
18
19  This program is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  GNU Affero General Public License for more details.
23
24  You should have received a copy of the GNU Affero General Public License
25  along with this program.  If not, see <http://www.gnu.org/licenses/>.
26
27  Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
28  are used without permission.  This program is not endorsed or
29  sponsored by Three Rings.
30
31
32  This Mason component generates the documentation.
33
34
35 </%doc>
36 <html><head><title>Website documentation - YARRG</title>
37 </head><body>
38
39 <a href="lookup">YARRG</a> -
40  Yet Another Revenue Research Gatherer
41 |
42 <a href="intro">introduction</a>
43 |
44 <b>documentation</b>
45
46 <h1>Looking up data in YARRG</h1>
47
48 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
49 for helping find profitable trades and trade routes in Yohoho Puzzle
50 Pirates.  See the <a href="intro">Introduction</a> for more details.
51
52 <p>
53
54 The <a href="lookup">Market prices database</a> is the main output
55 from YARRG.  It offers a variety of enquiry options.
56
57 <p>
58
59 This website documentation page contains information about the
60 database website which you may not be able to divine from the online
61 user interface.
62
63 <h2>Bookmarkable URLs</h2>
64
65 Mostly, you can bookmark the specific pages and queries.  Select the
66 ocean, query page, and other combinations of options, as you wish, and
67 perhaps fill in the actual data fields too, and bookmark the resulting
68 URL.
69
70 <p>
71
72 (An exception to this is if you select the `Update' option from the
73 `Trades for route' lookup; the list of (de)selected stalls is too long
74 to fit in a URL.)
75
76 <h2>Dynamic confirmation of meaning of text entry boxes</h2>
77
78 If you have Javascript enabled, the various text entry boxes will be
79 annotated with a brief explanation of the system's interpretation of
80 your current entry string.  To get the actual results updated, you
81 must still hit `Go' or `Update'.
82
83 <h2>Trades for route</h2>
84
85 Given a list of islands (or archipelagoes), provides a list of
86 potentially profitable trades.  If the route is suitable for the trade
87 route optimiser, it will generate a complete voyage plan, telling you
88 which goods to buy and sell where at which stalls and prices.
89
90 <p>
91
92 If you specify only one island or one archipelago, the site shows only
93 arbitrage trades.  If you want single-hop trades within an
94 archipelago, you must enter the archipelago name twice.
95
96 <p>
97
98 After getting the results, you can untick various trades individually,
99 and select `Update' to get a new plan.  The unticked trades will be
100 excluded from the voyage plan (if any) and also from the totals.
101
102 <h3>Vessel capacity</h3>
103
104 If you don't specify a vessel or a vessel capacity, the trading plan
105 will not take into account the fact that your voyage will be on a ship
106 with a limited size.  This will probably result in a plan
107 which trades excessively cumbersome goods (eg. hemp, wood, iron).
108
109 <p>
110
111 So you should specify your vessel capacity.  Currently you must
112 specify the actual mass and volume, as two numbers each with units.
113 The system understands the units t (tonnes), kg, l and kl
114 (kilolitres).  There should be a space between the two limits, and no
115 space before the unit.
116
117 <h3>Expected losses</h3>
118
119 In theory if you were guaranteed to have a trouble-free voyage it
120 would be worth trading goods at very low margins.  However, in
121 practice problems can arise: you may be attacked and lose your stock,
122 or market conditions may change between your collection and delivery
123 of the goods.
124
125 <p>
126
127 We model this by pretending that you expect to lose a fixed proportion
128 of your stock each league you sail.  This expected loss does not
129 appear in the trade tables (although the distance does), but it does
130 affect the way the voyage trading plan optimiser chooses which trades
131 to do.
132
133 <p>
134
135 Trades whose margin is less than the expected loss are never selected.
136 For example, if you select 1% loss per league, and plan a voyage of 5
137 leagues, then any trade with a margin of less than 5.15% would be
138 completely excluded (5.15% not 5% because the loss works like compound
139 interest).  Theoretically very profitable trades which are close to
140 the expected break-even point because of the distance can also be
141 rejected by the optimiser in favour of shorter distance trades with
142 theoretically smaller margins.
143
144 <p>
145
146 As a guide: you may expect to lose between 0.1% and 1% per league.
147 0.1% would correspond, for example, to losing one fight to brigands
148 every ten 10-league voyages.
149
150 <p>
151
152 You can enter the value in the box either as a percentage, or as a
153 fraction 1/<em>divisor</em>, eg 1/200 is the same as 0.5%; in each
154 case it is taken as the loss for each league of the voyage.
155
156 <& footer &>