Package: significantdigits
significantdigits package - v0.3.0Compute the number of significant digits based on the paperConfidence Intervals for Stochastic Arithmetic.
This package is also inspired by theJupyter Notebookincluded with the publication.Getting startedThis synthetic example illustrates how to compute significant digits
of a results sample with a given known reference:>>>importsignificantdigitsassd>>>importnumpyasnp>>>fromnumpy.randomimportuniformasU>>>np.random.seed(0)>>>eps=2**-52>>># simulates results with epsilon differences>>>X=[1+U(-1,1)*epsfor_inrange(10)]>>>sd.significant_digits(X,reference=1)>>>51.02329058847853or with the CLI interface assumingXis intest.txt:>significantdigits--metricsignificant-i"$(cattest.txt)"--input-formatstdin--reference1>(51.02329058847853,)If the reference is unknown, one can use the sample average:...>>>sd.significant_digits(X,reference=np.mean(X))>>>51.02329058847853Installationpython3-mpipinstall-Usignificantdigitsor if you want the latest version of the code, you can install itfromthe repository directlypython3-mpipinstall-Ugit+https://github.com/verificarlo/significantdigits.git# or if you don't have 'git' installedpython3-mpipinstall-Uhttps://github.com/verificarlo/significantdigits/zipball/masterAdvanced UsageInputs typesFunctions accept the following types of inputs:InputType:ArrayLikeThose types are accessible with thenumpy.typing.ArrayLiketype.Z computationMetrics are computed using Z, the distance between the samples and the reference.
There are four possible cases depending on the distance and the nature of the reference that are summarized in this table:constant reference (x)random variable reference (Y)Absolute precisionZ = X - xZ = X - YRelative precisionZ = X/x - 1Z = X/Y - 1_compute_z(array:InternalArrayType,reference:InternalArrayType|None,error:Error|str,axis:int,shuffle_samples:bool=False)->InternalArrayTypeComputeZ,thedistancebetweentherandomvariableandthereferenceComputeZ,thedistancebetweentherandomvariableandthereferencewiththreecasesdependingonthedimensionsofarrayandreference:X=arrayY=referenceThreecases:-YisnoneThecasewhenX=YWesplitXintwoandsetonegrouptoXandtheothertoY-X.ndim==Y.ndimXandYhavethesamedimensionItitthecasewhenYisarandomvariable-X.ndim-1==Y.ndimorY.ndim==0YisascalarvalueParameters----------array:InternalArrayTypeTherandomvariablereference:Optional[InternalArrayType]Thereferencetocompareagainsterror:Error|strTheerrorfunctiontocomputeZaxis:int,default=0TheaxisoraxesalongwhichcomputeZshuflle_samples:bool,default=FalseIfTrue,shufflesthegroupswhenthereferenceisNoneReturns-------array:InternalArrayTypeTheresultofZfollowingtheerrormethodchooseMethodsTwo methods exist for computing both significant and contributing digits depending on whether the sample follows a Centered Normal distribution or not.
You can pass the method to the function by using theMethodenum provided by the package.
The functions also accept the name as a string"cnh"forMethod.CNHand"general"forMethod.General.classMethod(AutoName):"""CNH: Centered Normality HypothesisX follows a Gaussian law centered around the reference orZ follows a Gaussian law centered around 0General: No assumption about the distribution of X or Z"""CNH=auto()General=auto()Significant digitssignificant_digits(array:InputType,reference:ReferenceType|None=None,axis:int=0,basis:int=2,error:Error|str,method:Method|str,probability:float=0.95,confidence:float=0.95,shuffle_samples:bool=False,dtype:DTypeLike|None=None)->ArrayLikeComputesignificantdigitsThisfunctioncomputeswithacertainprobabilitythenumberofbitsthataresignificant.Parameters----------array:InputTypeElementtocomputereference:ReferenceType|None,optional=NoneReferenceforcomparingthearrayaxis:int,optional=0Axisoraxesalongwhichthesignificantdigitsarecomputedbasis:int,optional=2Basisinwhichrepresentthesignificantdigitserror:Error|str,optional=Error.RelativeErrorfunctiontousetocomputeerrorbetweenarrayandreference.method:Method|str,optional=Method.CNHMethodtousefortheunderlyingdistributionhypothesisprobability:float,default=0.95Probabilityforthesignificantdigitsresultconfidence:float,default=0.95Confidencelevelforthesignificantdigitsresultshuffle_samples:bool,optional=FalseIfreferenceisNone,thearrayissplitintwoand\comparisonisdonebetweenbothpieces.\Ifshuffle_samplesisTrue,itshufflespieces.dtype:dtype_like|None,default=NoneNumericaltypeusedforcomputingsignificantdigitsWidestformatbetweenarrayandreferenceistakenifnosupplied.Returns-------ndarrayarray_likecontainingsignificantdigitsContributing digitscontributing_digits(array:InputType,reference:ReferenceType|None=None,axis:int=0,basis:int=2,error:Error|str,method:Method|str,probability:float=0.51,confidence:float=0.95,shuffle_samples:bool=False,dtype:DTypeLike|None=None)->ArrayLikeComputecontributingdigitsThisfunctioncomputeswithacertainprobabilitythenumberofbitsofthemantissathatwillroundtheresulttowardsthecorrectreferencevalue[1]_Parameters----------array:InputArrayElementtocomputereference:ReferenceArray|None,default=NoneReferenceforcomparingthearrayaxis:int,default=0Axisoraxesalongwhichthecontributingdigitsarecomputeddefault:Nonebasis:int,optional=2basisinwhichrepresentthecontributingdigitserror:Error|str,default=Error.RelativeErrorfunctiontousetocomputeerrorbetweenarrayandreference.method:Method|str,default=Method.CNHMethodtousefortheunderlyingdistributionhypothesisprobability:float,default=0.51Probabilityforthecontributingdigitsresultconfidence:float,default=0.95Confidencelevelforthecontributingdigitsresultshuffle_samples:bool,default=FalseIfreferenceisNone,thearrayissplitintwoandcomparisonisdonebetweenbothpieces.Ifshuffle_samplesisTrue,itshufflespieces.dtype:dtype_like|None,default=NoneNumericaltypeusedforcomputingcontributingdigitsWidestformatbetweenarrayandreferenceistakenifnosupplied.Returns-------ndarrayarray_likecontainingcontributingdigitsUtils functionThese are utility functions for the general case.probability_estimation_generalEstimates the lower bound probability given the sample size.probability_estimation_general(success:int,trials:int,confidence:float)->floatComputesprobabilitylowerboundforBernouilliprocessThisfunctioncomputestheprobabilityassociatedwithmetricscomputedinthegeneralcase(withoutassumptionontheunderlyingdistribution).Indeed,inthatcasetheprobabilityisgivenbythesamplesizewithacertainconfidencelevel.Parameters----------success:intNumberofsuccessforaBernoulliexperimenttrials:intNumberoftrialsforaBernoulliexperimentconfidence:floatConfidencelevelfortheprobabilitylowerboundestimationReturns-------floatThelowerboundprobabilitywith`confidence`leveltohave`success`successesfor`trials`trialsminimum_number_of_trialsReturns the minimal sample size required to reach the requestedprobabilityandconfidence.minimum_number_of_trials(probability:float,confidence:float)->intComputestheminimumnumberoftrialstohaveprobabilityandconfidenceThisfunctioncomputestheminimalsamplesizerequiredtohavemetricswithacertainprobabilityandconfidenceforthegeneralcase(withoutassumptionontheunderlyingdistribution).Forexample,ifonewantssignificantdigitswithproababilityp=99%andconfidence(1-alpha)=95%,itrequiresatleast299observations.Parameters----------probability:floatProbabilityconfidence:floatConfidenceReturns-------intMinimalsamplesizetohavegivenprobabilityandconfidenceLicenseThis file is part of the Verificarlo project,
under the Apache License v2.0 with LLVM Exceptions.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception.
Seehttps://llvm.org/LICENSE.txtfor license information.Copyright (c) 2020-2023 Verificarlo Contributors