Guia de Precisió i Toleràncies a Beancount

La gestió de la precisió numèrica és una pedra angular de la comptabilitat per partida doble. En la comptabilitat digital, especialment quan es tracta de múltiples divises, preus d'accions i accions fraccionàries, petites discrepàncies d'arrodoniment poden portar ràpidament a frustrants errors d'equilibri. Beancount proporciona un sistema sofisticat però intuïtiu per gestionar la precisió i establir toleràncies acceptables. Aquesta guia us guiarà per com funciona. ⚙️

Conceptes bàsics de precisió

L'objectiu principal de Beancount és assegurar que cada transacció s'equilibri a zero. No obstant això, els càlculs que impliquen preus o costos sovint produeixen resultats amb més decimals dels que són pràctics de registrar. El sistema de tolerància permet petits desequilibris acceptables.

Inferencia automàtica de la tolerància

Per defecte, Beancount infereix automàticament la tolerància necessària per a cada transacció. Aquesta inferència es gestiona individualment per a cada transacció i es calcula per separat per a cada divisa implicada.

La regla és simple: la tolerància és la meitat de l'últim dígit significatiu dels números presents a les entrades de la transacció.

Per exemple, considereu aquesta compra:

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

Beancount infereix les toleràncies de la següent manera:

• Per a la divisa FUND, el número 10.22626 té 5 decimals. La tolerància és la meitat de l'últim dígit, per tant $0.00001 \\div 2 = 0.000005$ FUND.
• Per a la divisa USD, el número -384.61 té 2 decimals. La tolerància és la meitat de l'últim dígit, per tant $0.01 \\div 2 = 0.005$ USD.

Regles de pes de la transacció

Quan es comprova si una transacció s'equilibra, Beancount calcula el "pes" de cada entrada. Les regles per a aquest càlcul són:

1. Import simple: Si una entrada només té un import (p. ex., Assets:Cash -100.00 USD), el seu pes és aquest import exacte.
2. Entrada de preu: Si una entrada té un preu per unitat (p. ex., 10 FUND @ 38.46 USD), el seu pes és import × preu.
3. Entrada de cost: Si una entrada té un cost total (p. ex., 10 FUND {384.61 USD}), el seu pes és l'import del cost total.
4. Cost i preu: Si una entrada té tant un cost total com un preu per unitat (p. ex., 10 FUND {384.61 USD} @ 38.46 USD), només s'utilitza el cost total per a l'equilibri. El preu per unitat es tracta com un comentari o una nota.

Regles d'inferència de precisió

El sistema d'inferència automàtica segueix algunes regles específiques:

1. Format de número

• Els imports enters (p. ex., 10 USD) no contribueixen a la inferència de precisió.
• La tolerància màxima que es pot inferir automàticament és 0.05 unitats (p. ex., d'un número com 10.1 USD). Si necessiteu una tolerància més gran, l'heu d'especificar manualment.
• Els costos i els preus (p. ex., {37.61 USD}) estan exclosos de la inferència de tolerància. Només s'utilitzen els imports principals de les entrades.
• Si les entrades per a la mateixa divisa tenen diferents precisions (p. ex., -10.10 USD i 5.123 USD), Beancount utilitza la tolerància més gruixuda (més gran). En aquest cas, es basaria en -10.10 USD, que donaria una tolerància de $0.005$ USD.

2. Gestió per defecte Podeu establir una tolerància predeterminada global o específica de la divisa si una transacció no té números amb decimals a partir dels quals inferir-la.

   ; Estableix una tolerància per defecte per a totes les divises sense regles explícites
   option "inferred_tolerance_default" "*:0.001"
   
   ; Estableix una tolerància per defecte específica per a USD
   option "inferred_tolerance_default" "USD:0.003"

3. Multiplicador de tolerància Podeu augmentar globalment totes les toleràncies inferides per un multiplicador fix. Això és útil per relaxar les comprovacions a tot el fitxer sense canviar cada transacció. Un multiplicador d'1.2 augmenta totes les toleràncies inferides en un 20%.

   option "inferred_tolerance_multiplier" "1.2"

4. Inferencia basada en el cost Tot i que els costos normalment s'ignoren per a la inferència de tolerància, podeu indicar a Beancount que els utilitzi. Això és útil quan l'import final (p. ex., una retirada d'efectiu) és el número més precís d'una transacció.

   option "infer_tolerance_from_cost" "TRUE"

Afirmacions d'equilibri

Les afirmacions d'equilibri (balance) s'utilitzen per verificar que l'equilibri del vostre compte coincideix amb un valor conegut en una data específica. També tenen una tolerància associada.

Format bàsic

De manera similar a les transaccions, la tolerància per a una afirmació balance s'infereix del nombre de decimals de l'import.

; Afirma que l'equilibri és 4.271 RGAGX amb una tolerància de ±0.0005
2015-05-08 balance Assets:Fund  4.271 RGAGX

; Afirma que l'equilibri és 4.27 RGAGX amb una tolerància de ±0.005
2015-05-08 balance Assets:Fund  4.27 RGAGX

L'equilibri calculat ha d'estar dins d'aquest interval. Per al segon exemple, qualsevol equilibri entre $4.265$ i $4.275$ superaria la comprovació.

Toleràncies explícites

Si la tolerància inferida no és adequada, podeu especificar-ne una explícitament mitjançant el caràcter de titlla (~).

; Afirma que l'equilibri és 4.271 RGAGX amb una tolerància personalitzada de ±0.01 RGAGX
2015-05-08 balance Assets:Fund  4.271 ~ 0.01 RGAGX

Aquí, l'afirmació passarà si l'equilibri calculat està entre $4.261$ i $4.281$ RGAGX.

Gestió d'arrodoniment

Per als casos en què s'esperen i s'accepten petits residuals dels càlculs, Beancount proporciona eines per gestionar-los sistemàticament.

Seguiment d'errors d'arrodoniment

Podeu designar un compte especial per recollir automàticament els errors d'arrodoniment. Això manté les vostres transaccions perfectament equilibrades escombrant petites quantitats sobrants en un sol lloc.

Primer, habiliteu l'opció i obriu el compte:

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

Ara, Beancount afegirà automàticament una tercera part a qualsevol transacció que no s'equilibri dins de la seva tolerància, registrant la diferència a Equity:RoundingError.

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

En aquesta transacció, $1.245 \\times 43.23 = 53.82135$. La transacció està desequilibrada per $-0.00135$ USD. Amb l'opció d'arrodoniment habilitada, Beancount internament la tracta com:

2013-02-23 * "Compra"
  Assets:Invest         1.245 RGAGX {43.23 USD}
  Assets:Cash          -53.82 USD
  Equity:RoundingError -0.00135 USD  ; Afegit automàticament

Precisió de número inferida

Beancount també pot utilitzar la configuració de tolerància per arrodonir automàticament els números abans que s'insereixin a les estructures de dades del llibre.

1. No s'ha especificat cap tolerància: si no es defineix cap tolerància, els números s'utilitzen a la seva màxima precisió. No es produeix cap arrodoniment.

2. Amb tolerància per defecte: si configureu una tolerància per defecte, els números es quantificaran a aquest nivell.

   option "default_tolerance" "USD:0.001"

   Amb aquesta configuració, un número com 53.82135 USD s'arrodoniria i s'emmagatzemaria com 53.821 USD.

3. Amb compte d'arrodoniment: si tant una tolerància per defecte com un compte d'arrodoniment estan actius, Beancount quantifica el número i captura el residual.

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

   Un número com 53.82135 USD s'emmagatzemaria com 53.82 USD, i el residual de -0.00135 USD es registraria a Equity:RoundingError.

Detalls d'implementació

Uns quants punts tècnics aclareixen com Beancount assoleix aquesta fiabilitat.

1. Representació de números: Beancount utilitza el mòdul decimal de Python, no números de coma flotant. Això permet fins a 28 decimals de precisió i evita els errors de representació binària comuns als flotants.

2. Classe DisplayContext: aquesta classe interna gestiona tot el format de número amb finalitats de visualització. Respecta la configuració de precisió específica de la divisa i pot formatar la sortida amb columnes alineades i comes.

3. Precisió vs. Tolerància: és fonamental distingir aquests dos conceptes:

• La precisió es refereix al format de visualització d'un número (quants decimals es mostren).
• La tolerància és la concessió per al desequilibri utilitzada durant les comprovacions de verificació.

Bones pràctiques ✨

Aquí hi ha algunes recomanacions pràctiques per gestionar la precisió al vostre llibre major.

Configuració inicial

Per a la majoria de llibres majors nous, aquesta és una configuració inicial robusta:

; Un valor per defecte raonable per a la majoria de les divises (p. ex., USD, EUR)
option "inferred_tolerance_default" "*:0.005"

; Un buffer del 10% en totes les toleràncies inferides
option "inferred_tolerance_multiplier" "1.1"

; Un compte per capturar tota la pols d'arrodoniment
option "account_rounding" "Equity:RoundingError"
2000-01-01 open Equity:RoundingError

Consells per a la resolució de problemes

Si trobeu errors d'equilibri:

• Afegiu dígits decimals a l'import d'una entrada per crear una inferència de tolerància local més ajustada i precisa.
• Utilitzeu toleràncies explícites (~) a les afirmacions balance que fallen a causa de discrepàncies predictibles.
• Feu un seguiment dels errors d'arrodoniment en un compte dedicat per veure on i amb quina freqüència es produeixen.
• Considereu la possibilitat d'establir valors per defecte específics de la divisa si tracteu amb freqüència divises que tenen convencions diferents (p. ex., JPY no té decimals).

Estratègia de migració

Quan apliqueu aquests conceptes a un llibre major existent i desordenat:

1. Comenceu amb una tolerància global generosa (p. ex., *:0.05) i un multiplicador alt per aconseguir que el fitxer es validi.
2. Ajusteu gradualment les toleràncies i corregiu els errors que apareixen.
3. Afegiu dígits explícits als imports de les transaccions problemàtiques per permetre que la inferència faci la seva feina.
4. Superviseu l'equilibri del compte d'arrodoniment. Un equilibri gran o de creixement ràpid pot indicar un problema sistèmic que necessita investigació.