Undocumented feature() function

Taking a short break from Java-related stuff in Matlab, I wanted to share and expand a reply I posted a short while ago on the StackOverflow forum, in response to a reader’s request to explain Matlab’s feature function. This article uses pure Matlab and is absolutely unrelated to Java, so those of you who are Java-phobic can be at ease trying this at home…

feature is an entirely undocumented and unsupported Matlab function, and unlike most other undocumented Matlab functions it actually does often change without prior notice between Matlab releases, so be very careful when using this function in your code.

feature accepts two arguments: the name of the feature and an optional new value. This is similar to get/set functions: When only one argument is supplied, Matlab returns the current feature value (like get), otherwise the value is modified (like set). In some rare cases (feature(‘timing’)), a third input argument is sometimes expected.

Feature names are case-insensitive. The built-in function system_dependent appears to be a synonym for feature (not exactly – some system_dependent features are unavailable in feature…). We can find several references to system_dependent online, mostly for old Matlab releases. There’s even an entry in the official Matlab FAQ (which has no usful info), and I’ve seen online references going all the way back to 1993…

One of the very rare official comments about this function says:

The system_dependent function is an unpublished function that we use for a variety of crufty things. It will most certainly change from time to time and possibly even go away completely. The system_dependent function performs different functionality on each of the platforms supported by MATLAB.

Several feature options have been reported over the years, mainly on the CSSM forum and also seen in the installed Matlab code base, as listed below (the code references are from the latest Matlab release – 7.10, aka R2010a). Note that many of these features may not work on your platform:

• feature(‘usehg2’,flag) – this apparently relates to a new Handle-Graphics implementation that is under development for the past few years (I think I saw references to HG2 as far back as 2007, possibly earlier). HG2 is automatically active when Matlab is started with -hgVersion 2 option. It appears that the numeric HG handles have been replaced with their object-oriented (Matlab class system) handle counterparts in HG2 (today these class-system handles can be gotten using the handle function). Some handle properties are not implemented in HG2, and some GUI elements appear missing (figure menubar and toolbar, for example), but the basic plots look similar to our familiar HG. If anyone has any further information about HG2 I would love to hear it…
• feature(‘useGBT2’) – “feature(‘useGBT2’) is only available when Matlab is started with -hgVersion 2 option.” – In /ja/xlate:15419; also see in: clf.m
• feature(‘HGUsingMatlabClasses’) – see hgrc.m, subplot.m, title.m, xlabel.m, ylabel.m, zlabel.m, mesh.m, surf.m, colorbar.m etc. etc.
• feature(‘JavaFigures’) – see propedit.m; disabled since R2007a when native (non-Java) Matlab figures were disabled.
• feature(‘UseJava’) – see usejava.m
• feature(‘ClearJava’,1) – see javaclasspath.m
• feature(‘SetPrecision’) – accepts values 24, 53 or 64
• feature(‘SetRound’) – accepts values 0, 0.5, Inf or -Inf
• feature(‘IsDebug’) – see here; controls Matlab assertions.
• feature(‘NewPrintAPI’) – see \toolbox\matlab\graphics\private\setup.m
• feature(‘accel’,’on/off’) – see here and here. There is also a related feature(‘JIT’,’on/off’) which appears to control a subset of feature(‘accel’).
• feature(‘GetOS’) – see ver.m
• feature(‘GetWinSys’) – see ver.m
• feature(‘GetPid’) – returns the Matlab process ID (well, actually the PID of its JVM but that’s the same PID as Matlab’s). Also see the similar java.lang.management.ManagementFactory.getRuntimeMXBean.getName.char. This latter function returns the PID mangled with the computer name (for example: ‘1234@My-desktop’).
• feature(‘GetCPU’) – see daqsupport.m (Data Acquisition Toolbox) and here
• feature(‘NumCores’) – returns the number of CPU cores seen by Matlab
• feature(‘NumThreads’) – see here
• feature(‘MemStats’), feature(‘DumpMem’), feature(‘ProcessMem’) – these are memory reports that are even recommended by official MathWorks tech notes (1,2), newsletter and technical solutions (1,2). Numerous references to these features can be found online.
• feature(‘CheckMallocMemoryUsage’) – see this official technical paper
• feature(‘CheckMallocHeapWalk’) – see here
• feature(‘ShowCommandWindow’) – see here = commandwindow
• feature(‘LogDir’) – see here = tempdir
• feature(‘HotLinks’) – used to disable hyperlinks in the Command Window. This is used by Word notebooks (see mwMatlabEval macro in the Microsoft Word template file %matlabroot%\notebook\pc\M-BOOK.DOT). Also see: info.m, mlint.m, doclink.m, guidefunc.m, displayEndOfDemoMessage.m
• feature(‘UseOldFileDialogs’) – see toolbox\matlab\uitools\private\usejavadialog.m
• feature(‘timing’) – For example: cpucount = feature(‘timing’,’cpucount’); There are several other 2nd arg options, as explained by the following informative error message:

  >> feature timing
  ??? Error using ==> feature
  Choose second argument from:
    'resolution_tictoc'  - Resolution of Tic/Toc clock in sec (double)
    'overhead_tictoc'    - Overhead of Tic/Toc command in sec (double)
    'cpucount'           - Current CPU cycles used (uint64) [Using utCPUcount]
    'getcpuspeed_tictoc' - Stored CPU cycles/sec (double) [Used by tic/toc]
    'cpuspeed'           - Current CPU cycles/sec (double) [Simple MathWorks]
    'winperfcount'       - Current CPU cycles used (uint64) [Windows call]
    'winperfspeed'       - Current CPU cycles/sec (double) [Windows call]
    'wintime'            - Current Windows time (uint32) [Windows call]
                           units: msec since startup [Wraps]
    'wintimeofday'       - Current time of day converted to file time (unit64)[Windows call]
                           units: 100 nsec since 01-Jan-1601 (UTC)
    'clocks_per_sec'     - clock() speed in cycles/sec [CLOCKS_PER_SEC]
   
  Choose second and third arguments from:
    'cpuspeed', double num             - Current CPU cycles/sec (double) [MathWorks - num iterations]
    'setcpuspeed_tictoc', double speed - Set the CPU cycles/sec [Used by tic/toc]
     uint64 arg2, uint64 arg3          - uint64 difference = arg2 - arg3 (uint64)

• feature(‘memtic’), feature(‘memtoc’) – possibly related to feature(‘timing’); mentioned in /ja/xlate:5780-5781
• feature(‘locale’) – see mlint.m, mtree.m, helpmenufcn.m
• feature(‘DefaultCharacterSet’) – see here
• feature(‘COM_SafeArraySingleDim’) – explained here and here.
• feature(‘COM_ActxProgidCheck’,flag) – see /help/techdoc/helpsearch/_533.cfs
• feature(‘FigureTools’) – see domymenu.m
• feature(‘TimeSeriesTools’,1) – see /help/techdoc/helpsearch/_533.cfs
• feature(‘launch_activation’, ‘forcecheck’) – see StudentActivationStatus.m
• feature(‘EightyColumns’,flag) – see matlabrc.m
• feature(‘GetSharedLibExt’) – see loadlibrary.m and /toolbox/matlab/audiovideo/private/privateMMReaderPluginSearch.m
• feature(‘GetDefaultPrinter’) – see printdlg.m, printopt.m
• feature(‘GetPrinterInfo’) – see pagesetupdlg.m
• feature(‘GetPrinterColor’) – see /toolbox/matlab/graphics/private/defaultprtcolor.m
• feature(‘GetSpecifiedPrinterPort’,printerName) – see /toolbox/matlab/graphics/private/send.m
• feature(‘ShowFigureWindows’) – see printjob.m, printtables.m, /toolbox/matlab/graphics/private/warnfiguredialog.m
• feature(‘SearchUDDClassesForHelp’) – see /toolbox/matlab/helptools/+helpUtils/@HelpProcess/getHelpText.m
• feature(‘AutomationServer’) – see notebook.m, enableservice.m = enableservice(‘AutomationServer’, true)
• feature(‘EnableDDE’,flag) – see enableservice.m = enableservice(‘DDEServer’, true)
• feature(‘GetUserWorkFolder’) – see userpath.m, savepath.m
• feature(‘DirsAddedFreeze’), feature(‘DirsAddedUnfreeze’) – see addpath.m
• feature(‘ToolboxFreeze’), feature(‘ToolboxUnfreeze’) – explained here
• feature(‘DirChangeHandleWarn’) – accepts ‘always’, ‘once’, ‘never’ or ‘status’. Mentioned in an official Matlab technical solution and also in changeNotificationAdvanced.m.
• feature(‘DirReloadMsg’) – accepts ‘on’, ‘off’ or ‘status’. See changeNotificationAdvanced.m and here.
• feature(‘RemoteCWDPolicy’) – accepts ‘Reload’, ‘TimecheckDir’, ‘TimecheckDirFile’, ‘TimecheckFile, ‘None’ or ‘status’. See changeNotification.m and here.
• feature(‘RemotePathPolicy’) – accepts ‘Reload’, ‘TimecheckDir’, ‘TimecheckDirFile’, ‘TimecheckFile, ‘None’ or ‘status’. See changeNotification.m, here and this official technical solution.
• feature(‘GetPref’,prefName) – returns the system preference value for the requested preference name in the global prefs file ([prefdir,’/matlab.prf’]) that is explained here.
• feature(‘IsDebugMode’) – mentioned here and several other online places
• feature(‘ForceFramesOnBottom’) – mentioned here

Oddly, some features are only accessible via system_dependent, and not via feature:

• system_dependent(‘builtinEditor’,flag) – see matlabrc.m
• system_dependent(‘miedit’,filename) – referenced here, here and in edit.m. See matlabrc.m.
• system_dependent(4,…) – See cedit.m, arrayviewfunc.m, dbmex.m, mexdebug.m. In addition to 4, I have seen references to features #2, 7-14, 44, 45, 1000-1003.
• system_dependent(12,flag) – See %matlabroot%\notebook\pc\M-BOOK.DOT macro InitFromSavedSettings.

The following are OpenGL-related features that are used in the opengl.m function:

• feature(‘OpenglMode’)
• feature(‘OpenGLLoadStatus’)
• feature(‘UseMesaSoftwareOpenGL’,1)- unix only
• feature(‘UseGenericOpengl’,1)
• feature(‘GetOpenglInfo’) = opengl(‘info’)
• feature(‘GetOpenglData’) = opengl(‘data’)
• feature(‘OpenGLVerbose’,1)

If you lasted this far you deserve a special treat: Last but not least we have feature(‘dwim’). Unfortunately, this feature sometimes fails on some systems…

Have you discovered or used any interesting feature? If so, please do share them in the comments section below