2/15/2016

MATH

Overview

Math The Commons Math User Guide - Numerical Analysis

4NumericalAnalysis

Downloads
LatestAPI
docs
(development)
Javadoc(3.6
release)
Javadoc(3.5
release)

4.1Overview
Theanalysispackageistheparentpackageforalgorithmsdealingwithrealvaluedfunctions
ofonerealvariable.Itcontainsdedicatedsubpackagesprovidingnumericalrootfinding,
integration,interpolationanddifferentiation.Italsocontainsapolynomialssubpackagethat
considerspolynomialswithrealcoefficientsasdifferentiablerealfunctions.

Javadoc(3.4.1
release)

Functionsinterfacesareintendedtobeimplementedbyusercodetorepresenttheirdomain

Javadoc(3.4
release)

theirroots,orintegratethem,or...Functionscanbemultivariateorunivariate,realvectorialor

Javadoc(3.3
release)
Javadoc(3.2
release)

problems.Thealgorithmsprovidedbythelibrarywillthenoperateonthesefunctiontofind
matrixvalued,andtheycanbedifferentiableornot.

4.2Errorhandling

Javadoc(3.1.1
release)

Foruserdefinedfunctions,whenthemethodencountersanerrorduringevaluation,users

Javadoc(3.1
release)

waytodothat,usingrootsolvingastheexample(thesameconstructshouldbeusedforODE

Javadoc(3.0
release)
Javadoc(2.2
release)
IssueTracking
Source
Repository
(current)
Wiki
Developers
Guide
Proposal

mustusetheirownuncheckedexceptions.Thefollowingexampleshowstherecommended
integratorsorforoptimizations).
privatestaticclassLocalExceptionextendsRuntimeException{

//thexvaluethatcausedtheproblem
privatefinaldoublex

publicLocalException(doublex){
this.x=x
}

publicdoublegetX(){
returnx

USERGUIDE

Contents
Overview
Statistics
Data
Generation
LinearAlgebra
Numerical
Analysis
Special
Functions

privatestaticclassMyFunctionimplementsUnivariateFunction{
publicdoublevalue(doublex){
doubley=hugeFormula(x)
if(somethingBadHappens){
thrownewLocalException(x)
}
returny

data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

1/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

Utilities

Complex
Numbers

Distributions

publicvoidcompute(){

Fractions

try{

Transform
Methods

solver.solve(maxEval,newMyFunction(a,b,c),min,max)

Geometry

//retrievethexvalue

Optimization

CurveFitting
LeastSquares
Ordinary
Differential
Equations
Genetic
Algorithms
Filters

}catch(LocalExceptionle){

Asshowninthisexampletheexceptionisreallysomethinglocaltousercodeandthereisa
guaranteeApacheCommonsMathwillnotmesswithit.Theuserissafe.

4.3Rootfinding

Machine
Learning

UnivariateSolver,UnivariateDifferentiableSolverandPolynomialSolverprovidemeanstofind

Exceptions

andpolynomialfunctionsrespectively.Arootisthevaluewherethefunctiontakesthevalue0.

rootsofunivariaterealvaluedfunctions,differentiableunivariaterealvaluedfunctions,
CommonsMathincludesimplementationsoftheseveralrootfindingalgorithms:

PROJECT
DOCUMENTATION

Project
Information
Project
Reports
COMMONS

Home

Rootsolvers
Name

Function
type

Convergence

Needs
initial
bracketing

Bracket
side
selection

Bisection

univariate
realvalued
functions

linear,
guaranteed

yes

yes

Brent
Dekker

univariate
realvalued
functions

superlinear,
guaranteed

yes

no

bracketing
nthorder
Brent

univariate
realvalued
functions

variable
order,
guaranteed

yes

yes

Illinois
Method

univariate
realvalued
functions

superlinear,
guaranteed

yes

yes

Laguerre's
Method

polynomial
functions

cubicfor
simpleroot,

yes

no

License
Components
Sandbox
Dormant
GENERAL
INFORMATION

Security
Volunteering
Contributing
Patches
Building
Components
Commons
ParentPom
Commons

data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

2/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

linearfor
multipleroot

BuildPlugin
Releasing
Components
Wiki
ASF

HowtheASF
works
GetInvolved
Developer
Resources
Sponsorship
Thanks

Muller's
Methodusing
bracketingto
dealwith
realvalued
functions

univariate
realvalued
functions

quadratic
closetoroots

yes

no

Muller's
Methodusing
modulusto
dealwith
realvalued
functions

univariate
realvalued
functions

quadratic
closetoroot

yes

no

Newton
Raphson's
Method

differentiable
univariate
realvalued
functions

quadratic,
non
guaranteed

no

no

Pegasus
Method

univariate
realvalued
functions

superlinear,
guaranteed

yes

yes

RegulaFalsi
(false
position)
Method

univariate
realvalued
functions

linear,
guaranteed

yes

yes

Ridder's
Method

univariate
realvalued
functions

superlinear

yes

no

Secant
Method

univariate
realvalued
functions

superlinear,
non
guaranteed

yes

no

Somealgorithmsrequirethattheinitialsearchintervalbracketstheroot(i.e.thefunction
valuesatintervalendpointshaveoppositesigns).Somealgorithmspreservebracketing
throughoutcomputationandallowusertospecifywhichsideoftheconvergenceintervalto
selectastheroot.Itisalsopossibletoforceasideselectionafteraroothasbeenfoundeven
foralgorithmsthatdonotprovidethisfeaturebythemselves.Thisisusefulforexamplein
sequentialsearch,forwhichanewsearchintervalisstartedafteraroothasbeenfoundin
ordertofindthenextroot.Inthiscase,usermustselectasidetoensurehisloopisnotstuck
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

3/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

ononerootandalwaysreturnthesamesolutionwithoutmakinganyprogress.
Therearenumerousnonobvioustrapsandpitfallsinrootfinding.First,theusualdisclaimers
duetothewayrealworldcomputerscalculatevaluesapply.Ifthecomputationofthefunction
providesnumericalinstabilities,forexampleduetobitcancellation,therootfindingalgorithms
maybehavebadlyandfailtoconvergeorevenreturnbogusvalues.Therewillnotnecessarily
beanindicationthatthecomputedrootiswayoffthetruevalue.Secondly,therootfinding
problemitselfmaybeinherentlyillconditioned.Thereisa"domainofindeterminacy",the
intervalforwhichthefunctionhasnearzeroabsolutevaluesaroundthetrueroot,whichmay
belarge.Evenworse,smallproblemslikeroundofferrormaycausethefunctionvalueto
"numericallyoscillate"betweennegativeandpositivevalues.Thismayagainresultinroots
wayoffthetruevalue,withoutindication.Thereisnotmuchagenericalgorithmcandoifill
conditionedproblemsaremet.Awayaroundthisistotransformtheprobleminordertogeta
betterconditionedfunction.Properselectionofarootfindingalgorithmanditsconfiguration
parametersrequiresknowledgeoftheanalyticalpropertiesofthefunctionunderanalysisand
numericalanalysistechniques.Usersareencouragedtoconsultanumericalanalysistext(ora
numericalanalyst)whenselectingandconfiguringasolver.
Inordertousetherootfindingfeatures,firstasolverobjectmustbecreatedbycallingits
constructor,oftenprovidingrelativeandabsoluteaccuracy.Usingasolverobject,rootsof
functionsareeasilyfoundusingthe solvemethods.Thesemethodstakesamaximum
iterationcount maxEval,afunction f,andeithertwodomainvalues, minand max,or
a startValueasparameters.Ifthemaximalnumberofiterationscountisexceeded,non
convergenceisassumedanda ConvergenceExceptionexceptionisthrown.Asuggested
valueis100,whichshouldbeplenty,giventhatabisectionalgorithmcan'tgetanymore
accurateafter52iterationsbecauseofthenumberofmantissabitsinadoubleprecision
floatingpointnumber.Ifanumberofillconditionedproblemsistobesolved,thisnumbercan
bedecreasedinordertoavoidwastingtime.Bracketedsolversalsotakeanallowed
solutionenumparametertospecifywhichsideofthefinalconvergenceintervalshouldbe
selectedastheroot.Itcan
be ANY_SIDE, LEFT_SIDE, RIGHT_SIDE, BELOW_SIDEor ABOVE_SIDE.Leftand
rightareusedtospecifytherootalongthefunctionparameteraxiswhilebelowandabove
refertothefunctionvalueaxis.Thesolvemethodscomputeavalue csuchthat:
f(c)=0.0(see"functionvalueaccuracy")
min<=c<=max(exceptforthesecantmethod,whichmayfindasolutionoutside
theinterval)
Typicalusage:
UnivariateFunctionfunction=//someuserdefinedfunctionobject
finaldoublerelativeAccuracy=1.0e12
finaldoubleabsoluteAccuracy=1.0e8
finalintmaxOrder=5
UnivariateSolversolver=newBracketingNthOrderBrentSolver(relativeA
ccuracy,absoluteAccuracy,maxOrder)
doublec=solver.solve(100,function,1.0,5.0,AllowedSolution.LEFT_S
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

4/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

IDE)

Forcebracketing,byrefiningabasesolutionfoundbyanonbracketingsolver:
UnivariateFunctionfunction=//someuserdefinedfunctionobject
finaldoublerelativeAccuracy=1.0e12
finaldoubleabsoluteAccuracy=1.0e8
UnivariateSolvernonBracketing=newBrentSolver(relativeAccuracy,abso
luteAccuracy)
doublebaseRoot=nonBracketing.solve(100,function,1.0,5.0)
doublec=UnivariateSolverUtils.forceSide(100,function,
newPegasusSolver(relativeAc
curacy,absoluteAccuracy),
baseRoot,1.0,5.0,AllowedS
olution.LEFT_SIDE)

The BrentSolverusestheBrentDekkeralgorithmwhichisfastandrobust.Ifthereare
multiplerootsintheinterval,orthereisalargedomainofindeterminacy,thealgorithmwill
convergetoarandomrootintheintervalwithoutindicationthatthereareproblems.
Interestingly,theexaminedtextbookimplementationsalldisagreeindetailsofthe
convergencecriteria.Alsoeachimplementationhadproblemsforoneofthetestcases,sothe
expressionshadtobefudgedfurther.Don'texpecttogetexactlythesamerootvaluesasfor
otherimplementationsofthisalgorithm.
The BracketingNthOrderBrentSolverusesanextensionoftheBrentDekkeralgorithm
whichusesinversenthorderpolynomialinterpolationinsteadofinversequadraticinterpolation,
andwhichallowsselectionofthesideoftheconvergenceintervalforresultbracketing.Thisis
nowtherecommendedalgorithmformostuserssinceithasthelargestorder,doesn'trequire
derivatives,hasguaranteedconvergenceandallowsresultbracketselection.
The SecantSolverusesastraightforwardsecantalgorithmwhichdoesnotbracketthe
searchandthereforedoesnotguaranteeconvergence.ItmaybefasterthanBrentonsome
wellbehavedfunctions.
The RegulaFalsiSolverisvariationofsecantpreservingbracketing,butthenitmaybe
slow,asoneendpointofthesearchintervalwillbecomefixedafterandonlytheotherend
pointwillconvergetotheroot,henceresultinginasearchintervalsizethatdoesnotdecrease
tozero.
The IllinoisSolverand PegasusSolverarewellknownvariationsofregulafalsithat
fixtheproblemofstuckendpointsbyslightlyweightingoneendpointtobalancetheintervalat
nextiteration.PegasusisoftenfasterthanIllinois.Pegasusmaybethealgorithmofchoicefor
selectingaspecificsideoftheconvergenceinterval.
The BisectionSolverisincludedforcompletenessandforestablishingafallbackin
casesofemergency.Thealgorithmissimple,mostlikelybugfreeandguaranteedtoconverge
eveninveryadversecircumstanceswhichmightcauseotheralgorithmstomalfunction.The
drawbackisofcoursethatitisalsoguaranteedtobeslow.
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

5/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

The UnivariateSolverinterfaceexposesmanypropertiestocontroltheconvergenceof
asolver.Theaccuracypropertiesaresetatsolverinstancecreationandcannotbechanged
afterwards,thereareonlygetterstoretrivevetheirvalues,nosettersareavailable.

Property

Purpose

Absolute
accuracy

TheAbsoluteAccuracyis(estimated)
maximaldifferencebetweenthe
computedrootandthetruerootofthe
function.Thisiswhatmostpeoplethink
ofas"accuracy"intuitively.Thedefault
valueischosenasasanevaluefor
mostrealworldproblems,forrootsin
therangefrom100to+100.For
accuratecomputationofrootsnear
zero,intherangeform0.0001to
+0.0001,thevaluemaybedecreased.
Forcomputingrootsmuchlargerin
absolutevaluethan100,thedefault
absoluteaccuracymayneverbe
reachedbecausethegivenrelative
accuracyisreachedfirst.

Relative
accuracy

TheRelativeAccuracyisthemaximal
differencebetweenthecomputedroot
andthetrueroot,dividedbythe
maximumoftheabsolutevaluesofthe
numbers.Thisaccuracymeasurement
isbettersuitedfornumerical
calculationswithcomputers,duetothe
wayfloatingpointnumbersare
represented.Thedefaultvalueis
chosensothatalgorithmswillgeta
resultevenforrootswithlargeabsolute
values,evenwhileitmaybeimpossible
toreachthegivenabsoluteaccuracy.

Function
value
accuracy

Thisvalueisusedbysomealgorithms
inordertopreventnumerical
instabilities.Ifthefunctionisevaluated
toanabsolutevaluesmallerthanthe
FunctionValueAccuracy,the
algorithmsassumetheyhitarootand
returnthevalueimmediately.The
defaultvalueisa"verysmallvalue".If
thegoalistogetanearzerofunction

data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

6/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

valueratherthananaccurateroot,
computationmaybespedupbysetting
thisvalueappropriately.

4.4Interpolation
AUnivariateInterpolatorisusedtofindaunivariaterealvaluedfunction fwhichforagiven
setoforderedpairs( xi , yi )yields f(x)
yi tothebestaccuracypossible.Theresultis
i=
providedasanobjectimplementingtheUnivariateFunctioninterface.Itcanthereforebe
evaluatedatanypoint,includingpointnotbelongingtotheoriginalset.Currently,onlyan
interpolatorforgeneratingnaturalcubicsplinesandapolynomialinterpolatorareavailable.
Thereisnointerpolatorfactory,mainlybecausetheinterpolationalgorithmismoredetermined
bythekindoftheinterpolatedfunctionratherthanthesetofpointstointerpolate.Therearen't
currentlyanyaccuracycontrolseither,asinterpolationaccuracyisingeneraldeterminedby
thealgorithm.
Typicalusage:
doublex[]={0.0,1.0,2.0}
doubley[]={1.0,1.0,2.0}
UnivariateInterpolatorinterpolator=newSplineInterpolator()
UnivariateFunctionfunction=interpolator.interpolate(x,y)
doubleinterpolationX=0.5
doubleinterpolatedY=function.value(x)
System.outprintln("f("+interpolationX+")="+interpolatedY)

Anaturalcubicsplineisafunctionconsistingofapolynomialofthirddegreeforeach
subintervaldeterminedbythexcoordinatesoftheinterpolatedpoints.Afunction
interpolating Nvaluepairsconsistsof N1polynomials.Thefunctioniscontinuous,smooth
andcanbedifferentiatedtwice.Thesecondderivativeiscontinuousbutnotsmooth.Thex
valuespassedtotheinterpolatormustbeorderedinascendingorder.Itisnotvalidtoevaluate
thefunctionforvaluesoutsidetherange x0 .. xN .
ThepolynomialfunctionreturnedbytheNeville'salgorithmisasinglepolynomialguaranteed
topassexactlythroughtheinterpolationpoints.Thedegreeofthepolynomialisthenumberof
pointsminus1(i.e.theinterpolationpolynomialforathreepointssetwillbeaquadratic
polynomial).Despitethefacttheinterpolatingpolynomialsisaperfectapproximationofa
functionatinterpolationpoints,itmaybealooseapproximationbetweenthepoints.Due
toRunge'sphenomenomtheerrorcangetworseasthedegreeofthepolynomialincreases,
soaddingmorepointsdoesnotalwaysleadtoabetterinterpolation.
Loess(orLowess)interpolationisarobustinterpolationusefulforsmoothingunivariate
scaterplots.IthasbeendescribedbyWilliamClevelandinhis1979seminalpaperRobust
LocallyWeightedRegressionandSmoothingScatterplots.Thiskindofinterpolationis
computationallyintensivebutrobust.

data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

7/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

Microsphereinterpolationisarobustmultidimensionalinterpolationalgorithm.Ithasbeen
describedinWilliamDudziak'sMSthesis.
Hermiteinterpolationisaninterpolationmethodthatcanusederivativesinadditiontofunction
valuesatsamplepoints.TheHermiteInterpolatorclassimplementsthismethodforvector
valuedfunctions.Thesamplingpointscanhaveanyspacing(therearenorequirementsfora
regulargrid)andsomepointsmayprovidederivativeswhileothersdon'tprovidethem(or
providederivativestoasmallerorder).Pointsareaddedoneatatime,asshowninthe
followingexample:
HermiteInterpolatorinterpolator=newHermiteInterpolator
//atx=0,weprovidebothvalueandfirstderivative
interpolator.addSamplePoint(0.0,newdouble[]{1.0},newdouble[]{
2.0})
//atx=1,weprovideonlyfunctionvalue
interpolator.addSamplePoint(1.0,newdouble[]{4.0})
//atx=2,weprovidebothvalueandfirstderivative
interpolator.addSamplePoint(2.0,newdouble[]{5.0},newdouble[]{
2.0})
//shouldprint"valueatx=0.5:2.5625"
System.out.println("valueatx=0.5:"+interpolator.value(0.5)[0])
//shouldprint"derivativeatx=0.5:3.5"
System.out.println("derivativeatx=0.5:"+interpolator.derivativ
e(0.5)[0])
//shouldprint"interpolationpolynomial:1+2x+4x^24x^3+
x^4"
System.out.println("interpolationpolynomial:"+interpolator.getPolyn
omials()[0])

ABivariateGridInterpolatorisusedtofindabivariaterealvaluedfunction fwhichforagiven
setoftuples( xi , yj , fij )yields f(x,
fij tothebestaccuracypossible.Theresult
i y)
j=
isprovidedasanobjectimplementingtheBivariateFunctioninterface.Itcanthereforebe
evaluatedatanypoint,includingapointnotbelongingtotheoriginalset.The
arrays xi and yj mustbesortedinincreasingorderinordertodefineatwodimensional
grid.
Inbicubicinterpolation,theinterpolationfunctionisa3rddegreepolynomialoftwovariables.
Thecoefficientsarecomputedfromthefunctionvaluessampledonagrid,aswellasthe
valuesofthepartialderivativesofthefunctionatthosegridpoints.Fromtwodimensionaldata
sampledonagrid,theBicubicSplineInterpolatorcomputesabicubicinterpolatingfunction.Prior
tocomputinganinterpolatingfunction,
theSmoothingPolynomialBicubicSplineInterpolatorclassperformssmoothingofthedataby
computingthepolynomialthatbestfitseachoftheonedimensionalcurvesalongeachofthe
coordinateaxes.
ATrivariateGridInterpolatorisusedtofindatrivariaterealvaluedfunction fwhichforagiven
setoftuples( xi , yj , zk , fijk )yields f(x,
fijk tothebestaccuracypossible.
i y,
j z)
k=
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

8/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

TheresultisprovidedasanobjectimplementingtheTrivariateFunctioninterface.Itcan
thereforebeevaluatedatanypoint,includingapointnotbelongingtotheoriginalset.The
arrays xi , yj and zk mustbesortedinincreasingorderinordertodefineathree
dimensionalgrid.
Intricubicinterpolation,theinterpolationfunctionisa3rddegreepolynomialofthreevariables.
Thecoefficientsarecomputedfromthefunctionvaluessampledonagrid,aswellasthe
valuesofthepartialderivativesofthefunctionatthosegridpoints.Fromthreedimensional
datasampledonagrid,theTricubicSplineInterpolatorcomputesatricubicinterpolating
function.

4.5Integration
AUnivariateIntegratorprovidesthemeanstonumericallyintegrateunivariaterealvalued
functions.CommonsMathincludesimplementationsofthefollowingintegrationalgorithms:
Romberg'smethod
Simpson'smethod
trapezoidmethod
LegendreGaussmethod

4.6Polynomials
Theorg.apache.commons.math3.analysis.polynomialspackageprovidesrealcoefficients
polynomials.
ThePolynomialFunctionclassisthemostgeneralone,usingtraditionalcoefficientsarrays.
ThePolynomialsUtilsutilityclassprovidesstaticfactorymethodstobuildChebyshev,Hermite,
Jacobi,LaguerreandLegendrepolynomials.Coefficientsarecomputedusingexactfractions
sothesefactorymethodscanbuildpolynomialsuptoanydegree.

4.7Differentiation
Theorg.apache.commons.math3.analysis.differentiationpackageprovidesageneralpurpose
differentiationframework.
ThecoreclassisDerivativeStructurewhichholdsthevalueandthedifferentialsofafunction.
Thisclasshandlessomearbitrarynumberoffreeparametersandarbitraryderivationorder.It
isusedbothastheinputandtheoutputtypefortheUnivariateDifferentiableFunctioninterface.
Anydifferentiablefunctionshouldimplementthisinterface.
ThemainideabehindtheDerivativeStructureclassisthatitcanbeusedalmostasanumber
(i.e.itcanbeadded,multiplied,itssquarerootcanbeextractedoritscosinecomputed...
However,inadditiontocomputedthevalueitselfwhendoingthesecomputations,thepartial
derivativesarealsocomputedalongside.Thisisanextensionofwhatissometimescalled
Rall'snumbers.ThisextensionisdescribedinDanKalman'spaperDoublyRecursive
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20b

9/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

MultivariateAutomaticDifferentiation,MathematicsMagazine,vol.75,no.3,June2002.Rall's
numbersonlyholdthefirstderivativewithrespecttoonefreeparameterwhereasDan
Kalman'sderivativestructuresholdallpartialderivativesuptoanyspecifiedorder,withrespect
toanynumberoffreeparameters.Rall'snumbersthereforecanbeseenasderivative
structuresfororderonederivativeandonefreeparameter,andprimitiverealnumberscanbe
seenasderivativestructureswithzeroorderderivativeandnofreeparameters.
Theworkflowofcomputationofaderivativesofanexpression y=f(x)isthefollowingone.
Firstweconfigureaninputparameter xoftypeDerivativeStructuresoitwilldrivethefunction
tocomputeallderivativesuptoorder3forexample.Thenwecompute y=f(x)normallyby
passingthisparametertotheffunction.Attheend,weextractfrom ythevalueandthe
derivativeswewant.Aswehavespecified3rdorderwhenwebuilt x,wecanretrievethe
derivativesupto3rdorderfrom y.Thefollowingexampleshowsthat(the0parameterinthe
DerivativeStructureconstructorwillbeexplainedinthenextparagraph):
intparams=1
intorder=3
doublexRealValue=2.5
DerivativeStructurex=newDerivativeStructure(params,order,0,xReal
Value)
DerivativeStructurey=f(x)
System.out.println("y="+y.getValue()
System.out.println("y'="+y.getPartialDerivative(1)
System.out.println("y''="+y.getPartialDerivative(2)
System.out.println("y'''="+y.getPartialDerivative(3)

Infact,therearenonotionsofvariablesintheframework,soneither xnor yareconsidered

tobevariablesperse.Theyarebothconsideredtobefunctionsandtodependonimplicitfree
parameterswhicharerepresentedonlybyindicesintheframework.The xinstanceaboveis
thereconsideredbytheframeworktobeafunctionoffreeparameter p0atindex0,and
as yiscomputedfrom xitistheresultofafunctionscompositionandisthereforealsoa
functionofthis p0freeparameter.The p0isnotrepresentedbyitself,itissimplydefined
implicitelybythe0indexabove.Thisindexisthethirdargumentintheconstructorof
the xinstance.Whatthisconstructormeansisthatwebuilt xasafunctionthatdepends
ononefreeparameteronly(firstconstructorargumentsetto1),thatcanbedifferentiatedupto
order3(secondconstructorargumentsetto3),andwhichcorrespondtoanidentityfunction
withrespecttoimplicitfreeparameternumber0(thirdconstructorargumentsetto0),with
currentvalueequalto2.5(fourthconstructorargumentsetto2.5).Thisspecificconstructor
definesidentityfunctions,andidentityfunctionsarethetrickweusetorepresentvariables
(thereareofcourseotherconstructors,forexampletobuildconstantsorfunctionsfromall
theirderivativesiftheyareknownbeforehand).Fromtheuserpointofview,the xinstance
canbeseenasthe xvariable,butitisreallytheidentityfunctionappliedtofreeparameter
number0.Astheidentityfunction,ithasthesamevalueasitsparameter,itsfirstderivativeis
1.0withrespecttothisfreeparameter,andallitshigherorderderivativesare0.0.Thiscanbe
checkedbycallingthegetValue()orgetPartialDerivative()methodson x.
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20

10/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

Whenwecompute yfromthissetting,whatwereallydoischain faftertheidentity

function,sothenetresultisthatthederivativesarecomputedwithrespecttotheindexedfree
parameters(i.e.onlyfreeparameternumber0heresincethereisonlyonefreeparameter)of
theidentityfunctionx.Goingonestepfurther,ifwecompute z=g(y),wewillalso
compute zasafunctionoftheinitialfreeparameter.Theveryimportantconsequenceisthat
ifwecall z.getPartialDerivative(1),wewillnotgetthefirstderivativeof gwith
respectto y,butwithrespecttothefreeparameter p0:thederivativesofgandfwillbe
chainedtogetherautomatically,withoutuserintervention.
Thisdesignchoiceisaveryclassicaloneinmanyalgorithmicdifferentiationframeworks,either
basedonoperatoroverloading(liketheoneweimplementedhere)orbasedoncode
generation.Itimpliestheuserhastobootstrapthesystembyprovidinginitialderivatives,and
thisisessentiallydonebysettingupidentityfunction,i.e.functionsthatrepresentthevariables
themselvesandhaveonlyunitfirstderivative.
Thisdesignalsoallowaveryinterestingfeaturewhichcanbeexplainedwiththefollowing
example.Supposewehaveatwoargumentsfunction fandaoneargumentfunction g.If
wecompute g(f(x,y))with xand ybetwovariables,wewanttobeabletocompute
thepartialderivatives dg/dx, dg/dy, d2g/dx2 d2g/dxdy d2g/dy2.Thisdoes
makesensesincewecombinedthetwofunctions,anditdoesmakesensedespitegisaone
argumentfunctiononly.Inordertodothis,wesimplysetup xasanidentityfunctionofan
implicitfreeparameter p0and yasanidentityfunctionofadifferentimplicitfree
parameter p1andcomputeeverythingdirectly.Inordertobeabletocombineeverything,
however,both xand ymustbebuiltwiththeappropriatedimensions,sotheywillbothbe
declaredtohandletwofreeparameters,but xwilldependonlyonparameter0while ywill
dependonparameter1.Hereishowwedothis(notethat getPartialDerivativeisa
variableargumentsmethodwhichtakeasargumentsthederivationorderwithrespecttoall
freeparameters,i.e.thefirstargumentisderivationorderwithrespecttofreeparameter0and
thesecondargumentisderivationorderwithrespecttofreeparameter1):
intparams=2
intorder=2
doublexRealValue=2.5
doubleyRealValue=1.3
DerivativeStructurex=newDerivativeStructure(params,order,0,xReal
Value)
DerivativeStructurey=newDerivativeStructure(params,order,1,yReal
Value)
DerivativeStructuref=DerivativeStructure.hypot(x,y)
DerivativeStructureg=f.log()
System.out.println("g="+g.getValue()
System.out.println("dg/dx="+g.getPartialDerivative(1,0)
System.out.println("dg/dy="+g.getPartialDerivative(0,1)
System.out.println("d2g/dx2="+g.getPartialDerivative(2,0)
System.out.println("d2g/dxdy="+g.getPartialDerivative(1,1)
System.out.println("d2g/dy2="+g.getPartialDerivative(0,2)
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20

11/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

Thereareseveralwaysausercancreateanimplementationof
theUnivariateDifferentiableFunctioninterface.Thefirstmethodistosimplywriteitdirectly
usingtheappropriatemethodsfromDerivativeStructuretocomputeaddition,subtraction,sine,
cosine...Thisisoftenquitestraigthforwardandthereisnoneedtoremembertherulesfor
differentiation:theusercodeonlyrepresentthefunctionitself,thedifferentialswillbe
computedautomaticallyunderthehood.Thesecondmethodistowritea
classicalUnivariateFunctionandtopassittoanexistingimplementationof
theUnivariateFunctionDifferentiatorinterfacetoretrieveadifferentiatedversionofthesame
function.Thefirstmethodismoresuitedtosmallfunctionsforwhichuseralreadycontrolall
theunderlyingcode.Thesecondmethodismoresuitedtoeitherlargefunctionsthatwouldbe
cumbersometowriteusingtheDerivativeStructureAPI,orfunctionsforwhichuserdoesnot
havecontroltothefullunderlyingcode(forexamplefunctionsthatcallexternallibraries).
ApacheCommonsMathprovidesoneimplementationof
theUnivariateFunctionDifferentiatorinterface:FiniteDifferencesDifferentiator.Thisclasscreates
awrapperthatwillcalltheuserprovidedfunctiononagridsampleandwillusefinite
differencestocomputethederivatives.Ittakescareofboundariesifthevariableisnotdefined
onthewholerealline.Itispossibletousemorepointsthanstrictlyrequiredbythederivation
order(forexampleonecanspecifyan8pointsschemetocomputefirstderivativeonly).
However,onemustbeawarethattuningtheparametersforfinitedifferencesishighly
problemdependent.Choosingthewrongstepsizeorthewrongnumberofsamplingpoints
canleadtohugeerrors.Finitedifferencesarealsonotwellsuitedtocomputehighorder
derivatives.Hereisanexampleonhowthisimplementationcanbeused:
//functiontobedifferentiated
UnivariateFunctionbasicF=newUnivariateFunction(){
publicdoublevalue(doublex){
returnx*FastMath.sin(x)
}
})

//createadifferentiatorusing5pointsand0.01step
FiniteDifferencesDifferentiatordifferentiator=
newFiniteDifferencesDifferentiator(5,0.01)

//createanewfunctionthatcomputesboththevalueandthederivativ
es
//usingDerivativeStructure
UnivariateDifferentiableFunctioncompleteF=differentiator.differentia
te(basicF)

//nowwecancomputedisplaythevalueanditsderivatives
//herewedecidedtodisplayuptosecondorderderivatives,
//becausewefeedcompleteFwithorder2DerivativeStructureinstances
for(doublex=10x<10x+=0.1){
data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20

12/13

2/15/2016

Math The Commons Math User Guide - Numerical Analysis

DerivativeStructurexDS=newDerivativeStructure(1,2,0,x)
DerivativeStructureyDS=f.value(xDS)
System.out.format(Locale.US,"%7.3f%7.3f%7.3f%n",
yDS.getValue(),
yDS.getPartialDerivative(1),
yDS.getPartialDerivative(2))
}

NotethatusingFiniteDifferencesDifferentiatora>inordertohave
aUnivariateDifferentiableFunctionthatcanbeprovidedtoaNewtonRaphson'ssolverisavery
badidea.Thereasonisthatfinitedifferencesarenotreallyaccurateandneedslotsof
additionalcallstothebasicunderlyingfunction.Ifuserinitiallyhaveonlythebasicfunction
availableandneedstofinditsroots,itismuchmoreaccurateandmuchmoreefficienttousea
solverthatonlyrequiresthefunctionvaluesandnotthederivatives.Agoodchoiceisto
usebracketingnthorderBrentmethod,whichinfactconvergesfasterthanNewton
Raphson'sandcanbeconfiguredtoahighereorder(typically5)thanNewtonRaphsonwhich
isanorder2method.
AnotherimplementationoftheUnivariateFunctionDifferentiatorinterfaceisunderdevelopment
intherelatedprojectApacheCommonsNabla.Thisimplementationusesautomaticcode
analysisandgenerationatbinarylevel.However,attimeofwriting(end2012),thisprojectis
notyetsuitableforproductionuse.

data:text/html;charset=utf-8,%3Ctable%20class%3D%22layout-table%22%20style%3D%22max-width%3A%20100%25%3B%20

13/13