Een Gids voor Precisie & Toleranties in Beancount

Het beheren van numerieke precisie is een hoeksteen van dubbel boekhouden. In digitale boekhouding, vooral bij het werken met meerdere valuta, aandelenkoersen en fractionele aandelen, kunnen kleine afrondingsverschillen snel leiden tot frustrerende balansfouten. Beancount biedt een verfijnd maar intuïtief systeem voor het omgaan met precisie en het instellen van acceptabele toleranties. Deze gids leidt u door de werking ervan. ⚙️

Kernconcepten Precisie

Het primaire doel van Beancount is ervoor te zorgen dat elke transactie tot nul balanceert. Berekeningen met prijzen of kosten leveren echter vaak resultaten op met meer decimalen dan praktisch is om vast te leggen. Het tolerantiesysteem staat kleine, acceptabele onevenwichtigheden toe.

Automatische Tolerantie Afleiding

Standaard leidt Beancount automatisch de vereiste tolerantie voor elke transactie af. Deze afleiding wordt individueel voor elke transactie afgehandeld en afzonderlijk berekend voor elke betrokken valuta.

De regel is simpel: de tolerantie is de helft van het laatste significante cijfer van de getallen in de boekingen van de transactie.

Neem bijvoorbeeld deze aankoop:

2013-04-03 * "Koop Fonds"
  Assets:Fund     10.22626 FUND {37.61 USD}
  Assets:Cash     -384.61 USD

Beancount leidt de volgende toleranties af:

• Voor de FUND commodity heeft het getal 10.22626 5 decimalen. De tolerantie is de helft van het laatste cijfer, dus $0.00001 \\div 2 = 0.000005$ FUND.
• Voor de USD commodity heeft het getal -384.61 2 decimalen. De tolerantie is de helft van het laatste cijfer, dus $0.01 \\div 2 = 0.005$ USD.

Transactie Gewicht Regels

Bij het controleren of een transactie in evenwicht is, berekent Beancount het "gewicht" van elke boeking. De regels voor deze berekening zijn:

1. Simpel Bedrag: Als een boeking alleen een bedrag heeft (bijv. Assets:Cash -100.00 USD), is het gewicht precies dat bedrag.
2. Prijsboeking: Als een boeking een prijs per eenheid heeft (bijv. 10 FUND @ 38.46 USD), is het gewicht bedrag × prijs.
3. Kostenboeking: Als een boeking totale kosten heeft (bijv. 10 FUND {384.61 USD}), is het gewicht het totale kostenbedrag.
4. Kosten en Prijs: Als een boeking zowel totale kosten als een prijs per eenheid heeft (bijv. 10 FUND {384.61 USD} @ 38.46 USD), worden alleen de totale kosten gebruikt voor het balanceren. De prijs per eenheid wordt behandeld als een opmerking of memo.

Precisie Afleidingsregels

Het automatische afleidingssysteem volgt een paar specifieke regels:

1. Getalformaat

• Integer bedragen (bijv. 10 USD) dragen niet bij aan precisie afleiding.
• De maximale tolerantie die automatisch kan worden afgeleid is 0.05 eenheden (bijv. van een getal als 10.1 USD). Als u een grotere tolerantie nodig heeft, moet u deze handmatig specificeren.
• Kosten en prijzen (bijv. {37.61 USD}) zijn uitgesloten van tolerantie afleiding. Alleen de primaire bedragen van de boekingen worden gebruikt.
• Als boekingen voor dezelfde valuta verschillende precisies hebben (bijv. -10.10 USD en 5.123 USD), gebruikt Beancount de grofste (grootste) tolerantie. In dit geval zou het gebaseerd zijn op -10.10 USD, wat een tolerantie oplevert van $0.005$ USD.

2. Standaard Afhandeling U kunt een globale of valuta-specifieke standaard tolerantie instellen als een transactie geen getallen met decimalen heeft waaruit deze kan worden afgeleid.

   ; Stelt een standaard tolerantie in voor alle valuta zonder expliciete regels
   option "inferred_tolerance_default" "*:0.001"
   
   ; Stelt een specifieke standaard tolerantie in voor USD
   option "inferred_tolerance_default" "USD:0.003"

3. Tolerantie Vermenigvuldiger U kunt globaal alle afgeleide toleranties verhogen met een vaste vermenigvuldiger. Dit is handig om controles in uw hele bestand losser te maken zonder elke transactie te wijzigen. Een vermenigvuldiger van 1.2 verhoogt alle afgeleide toleranties met 20%.

   option "inferred_tolerance_multiplier" "1.2"

4. Kosten-gebaseerde Afleiding Hoewel kosten normaal gesproken worden genegeerd voor tolerantie afleiding, kunt u Beancount instrueren om ze te gebruiken. Dit is handig wanneer het uiteindelijke bedrag (bijv. een contante opname) het meest precieze getal in een transactie is.

   option "infer_tolerance_from_cost" "TRUE"

Balans Asserties

Balans asserties (balance) worden gebruikt om te verifiëren dat het saldo van uw account overeenkomt met een bekende waarde op een specifieke datum. Ze hebben ook een bijbehorende tolerantie.

Basisformaat

Net als bij transacties wordt de tolerantie voor een balance assertie afgeleid van het aantal decimalen in het bedrag.

; Asserteert dat het saldo 4.271 RGAGX is met een tolerantie van ±0.0005
2015-05-08 balance Assets:Fund  4.271 RGAGX

; Asserteert dat het saldo 4.27 RGAGX is met een tolerantie van ±0.005
2015-05-08 balance Assets:Fund  4.27 RGAGX

Het berekende saldo moet binnen dit bereik vallen. Voor het tweede voorbeeld zou elk saldo tussen $4.265$ en $4.275$ de controle doorstaan.

Expliciete Toleranties

Als de afgeleide tolerantie niet geschikt is, kunt u er expliciet een specificeren met behulp van het tilde (~) teken.

; Asserteert dat het saldo 4.271 RGAGX is met een aangepaste tolerantie van ±0.01 RGAGX
2015-05-08 balance Assets:Fund  4.271 ~ 0.01 RGAGX

Hier zal de assertie slagen als het berekende saldo tussen $4.261$ en $4.281$ RGAGX ligt.

Afronding Beheer

Voor gevallen waarin kleine restwaarden van berekeningen worden verwacht en acceptabel zijn, biedt Beancount tools om ze systematisch te beheren.

Afrondingsfout Tracking

U kunt een speciale account aanwijzen om afrondingsfouten automatisch te verzamelen. Dit houdt uw transacties perfect in evenwicht door kleine overgebleven bedragen naar één plaats te vegen.

Schakel eerst de optie in en open de account:

option "account_rounding" "Equity:RoundingError"
2000-01-01 open Equity:RoundingError

Nu voegt Beancount automatisch een derde been toe aan elke transactie die niet binnen de tolerantie balanceert, waarbij het verschil naar Equity:RoundingError wordt geboekt.

2013-02-23 * "Aankoop"
  Assets:Invest     1.245 RGAGX {43.23 USD}
  Assets:Cash      -53.82 USD

In deze transactie is $1.245 \\times 43.23 = 53.82135$. De transactie is onevenwichtig met $-0.00135$ USD. Met de afrondingsoptie ingeschakeld, behandelt Beancount dit intern als:

2013-02-23 * "Aankoop"
  Assets:Invest         1.245 RGAGX {43.23 USD}
  Assets:Cash          -53.82 USD
  Equity:RoundingError -0.00135 USD  ; Automatisch toegevoegd

Afgeleide Getal Precisie

Beancount kan ook tolerantie-instellingen gebruiken om getallen automatisch af te ronden voordat ze zelfs in de datastructuren van het boek worden ingevoegd.

1. Geen Tolerantie Gespecificeerd: Als er geen tolerantie is gedefinieerd, worden getallen gebruikt met hun volledige precisie. Er vindt geen afronding plaats.

2. Met Standaard Tolerantie: Als u een standaard tolerantie instelt, worden getallen gekwantiseerd naar dat niveau.

   option "default_tolerance" "USD:0.001"

   Met deze instelling zou een getal als 53.82135 USD worden afgerond en opgeslagen als 53.821 USD.

3. Met Afrondingsaccount: Als zowel een standaard tolerantie als een afrondingsaccount actief zijn, kwantiseert Beancount het getal en legt het restbedrag vast.

   option "default_tolerance" "USD:0.01"
   option "account_rounding" "Equity:RoundingError"

   Een getal als 53.82135 USD zou worden opgeslagen als 53.82 USD, en het $-0.00135$ USD restbedrag zou naar Equity:RoundingError worden geboekt.

Implementatie Details

Een paar technische punten verduidelijken hoe Beancount deze betrouwbaarheid bereikt.

1. Getalrepresentatie: Beancount gebruikt Python's decimal module, geen floating-point getallen. Dit maakt tot 28 decimalen precisie mogelijk en vermijdt de binaire representatiefouten die vaak voorkomen bij floats.

2. DisplayContext Klasse: Deze interne klasse behandelt alle getalformatteringen voor weergavedoeleinden. Het respecteert valuta-specifieke precisie-instellingen en kan de output formatteren met uitgelijnde kolommen en komma's.

3. Precisie vs. Tolerantie: Het is cruciaal om deze twee concepten te onderscheiden:

• Precisie heeft betrekking op het weergaveformaat van een getal (hoeveel decimalen worden weergegeven).
• Tolerantie is de toegestane onevenwichtigheid die wordt gebruikt tijdens verificatiecontroles.

Beste Praktijken ✨

Hier zijn enkele praktische aanbevelingen voor het beheren van precisie in uw grootboek.

Initiële Setup

Voor de meeste nieuwe grootboeken is dit een robuuste startconfiguratie:

; Een redelijke standaard voor de meeste valuta (bijv. USD, EUR)
option "inferred_tolerance_default" "*:0.005"

; Een buffer van 10% op alle afgeleide toleranties
option "inferred_tolerance_multiplier" "1.1"

; Een account om al het afrondingsstof op te vangen
option "account_rounding" "Equity:RoundingError"
2000-01-01 open Equity:RoundingError

Tips voor Probleemoplossing

Als u balansfouten tegenkomt:

• Voeg decimalen toe aan het bedrag van een boeking om een strakkere, nauwkeurigere lokale tolerantie afleiding te creëren.
• Gebruik expliciete toleranties (~) op balance asserties die mislukken vanwege voorspelbare verschillen.
• Volg afrondingsfouten in een speciale account om te zien waar en hoe vaak ze voorkomen.
• Overweeg om valuta-specifieke standaarden in te stellen als u vaak te maken heeft met valuta's die verschillende conventies hebben (bijv. JPY heeft geen decimalen).

Migratie Strategie

Bij het toepassen van deze concepten op een bestaand, rommelig grootboek:

1. Begin met een royale globale tolerantie (bijv. *:0.05) en een hoge vermenigvuldiger om het bestand te laten valideren.
2. Draai geleidelijk aan de toleranties aan en corrigeer de fouten die verschijnen.
3. Voeg expliciete cijfers toe aan bedragen in problematische transacties om afleiding zijn werk te laten doen.
4. Bewaak het saldo van de afrondingsaccount. Een groot of snel groeiend saldo kan een systemisch probleem signaleren dat onderzoek vereist.