Skip to main content

programming - Is using undocumented functionality a Bad Idea™?


Mathematica has a lot of very useful undocumented features. For example a hash table, a built-in list of compilable functions, additional options to CurrentValue, {"Raw", n} histogram bin specification, etc...


A natural question that arises is: Why is this functionality undocumented? Is it because the feature is under development? Or because the syntax has not been finalized and may be changed? Something else?


Also: Is using this functionality safe in the sense that it will not cause problems when a new version is released?



Answer



The two main arguments against using undocumented functions are:




  1. Your code might not work as expected in future versions;

  2. Your code might not work as you intended in the current version, because you only have a partial understanding of a function or option that is undocumented.


In the case of Mathematica, though, there is no guarantee that even documented functions will remain unchanged in future versions.



The two main arguments for using undocumented functions are:



  1. Oftentimes they presage the permanent inclusion of that functionality in a future version. For example, ScalingFunctions is only documented for charting functions like BarChart, but it has been shown to work also for ListPlot and Plot (but not DateListPlot). I predict that they will get around to completing (and documenting) this functionality in a future version. (EDIT: In fact, that's exactly what happened in 10.4, even though the online version of the documentation doesn't make it clear that this is new.)

  2. The functionality might be documented, but not completely documented. For example, some option values (say PlotRegion) are documented as applying to "graphics functions", without specifying which ones. So the functionality is there, and might well remain stable for several versions.



Mathematica is a complex system with an enormous array of possibilities for the use and abuse of its rich functionality. Even with the massive documentation that exists, there are bound to be some undocumented or incompletely documented functions. Undocumented functions (and options) need to used with some care, but given the usefulness of some of the functionality they offer, it might well be worth the risk.


Comments

Post a Comment

Popular posts from this blog

mathematical optimization - Minimizing using indices, error: Part::pkspec1: The expression cannot be used as a part specification

I want to use Minimize where the variables to minimize are indices pointing into an array. Here a MWE that hopefully shows what my problem is. vars = u@# & /@ Range[3]; cons = Flatten@ { Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; Minimize[{Total@((vec1[[#]] - vec2[[u[#]]])^2 & /@ Range[1, 3]), cons}, vars, Integers] The error I get: Part::pkspec1: The expression u[1] cannot be used as a part specification. >> Answer Ok, it seems that one can get around Mathematica trying to evaluate vec2[[u[1]]] too early by using the function Indexed[vec2,u[1]] . The working MWE would then look like the following: vars = u@# & /@ Range[3]; cons = Flatten@{ Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; NMinimize[ {Total@((vec1[[#]] - Indexed[vec2, u[#]])^2 & /@ R...
Post a Comment
Read more

functions - Get leading series expansion term?

Given a function f[x] , I would like to have a function leadingSeries that returns just the leading term in the series around x=0 . For example: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x)] x and leadingSeries[(1/x + 2 + (1 - 1/x^3)/4)/(4 + x)] -(1/(16 x^3)) Is there such a function in Mathematica? Or maybe one can implement it efficiently? EDIT I finally went with the following implementation, based on Carl Woll 's answer: lds[ex_,x_]:=( (ex/.x->(x+O[x]^2))/.SeriesData[U_,Z_,L_List,Mi_,Ma_,De_]:>SeriesData[U,Z,{L[[1]]},Mi,Mi+1,De]//Quiet//Normal) The advantage is, that this one also properly works with functions whose leading term is a constant: lds[Exp[x],x] 1 Answer Update 1 Updated to eliminate SeriesData and to not return additional terms Perhaps you could use: leadingSeries[expr_, x_] := Normal[expr /. x->(x+O[x]^2) /. a_List :> Take[a, 1]] Then for your examples: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x), x] leadingSeries[Exp[x], x] leadingSeries[(1/x + 2 + (1 - 1/x...
Post a Comment
Read more

What is and isn't a valid variable specification for Manipulate?

I have an expression whose terms have arguments (representing subscripts), like this: myExpr = A[0] + V[1,T] I would like to put it inside a Manipulate to see its value as I move around the parameters. (The goal is eventually to plot it wrt one of the variables inside.) However, Mathematica complains when I set V[1,T] as a manipulated variable: Manipulate[Evaluate[myExpr], {A[0], 0, 1}, {V[1, T], 0, 1}] (*Manipulate::vsform: Manipulate argument {V[1,T],0,1} does not have the correct form for a variable specification. >> *) As a workaround, if I get rid of the symbol T inside the argument, it works fine: Manipulate[ Evaluate[myExpr /. T -> 15], {A[0], 0, 1}, {V[1, 15], 0, 1}] Why this behavior? Can anyone point me to the documentation that says what counts as a valid variable? And is there a way to get Manpiulate to accept an expression with a symbolic argument as a variable? Investigations I've done so far: I tried using variableQ from this answer , but it says V[1...
Post a Comment
Read more