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

Related posts:

  1. Undocumented feature list A list of undocumented MATLAB features can be retrieved. Here's how... ...
  2. ismembc – undocumented helper function Matlab has several undocumented internal helper functions that can be useful on their own in some cases. This post presents the ismembc function....
  3. sprintfc – undocumented helper function The built-in sprintfc function can be used to quickly generate a cell-array of formatted strings. ...
  4. Legend ‘-DynamicLegend’ semi-documented feature The built-in Matlab legend function has a very useful semi-documented feature for automatic dynamic update, which is explained here....
  5. Undocumented cursorbar object Matlab's internal undocumented graphics.cursorbar object can be used to present dynamic data-tip cross-hairs...
  6. uiundo – Matlab’s undocumented undo/redo manager The built-in uiundo function provides easy yet undocumented access to Matlab's powerful undo/redo functionality. This article explains its usage....

Categories: High risk of breaking in future versions, Undocumented function

Tags: , ,

Bookmark and SharePrint Print

16 Responses to Undocumented feature() function

  1. Donn Shull says:

    Hi Yair, the following feature is only useful to people with Simulink and Real-Time Workshop Embedded Coder. If you open a block diagram for example:

    >> rtwdemo_fuelsys

    you can obtain the object instance for your block diagram with:

    >> obj = get_param(bdroot, 'UDDObject')

    This object has a lot of useful methods but many of them raise an exception for example:

    >> obj.getCompiledBlockList
    ??? Simulink engine interface is not enabled.

    Using the engine interface feature will enable those methods

    >> feature('EngineInterface', 1)

    Will enable those methods.

    On a related topic as an alternative to using handle to obtain the object for handle graphics items you can create them with a “package qualified” command and they will return the object rather than a numeric handle. for example:

    >> figObj = hg.figure
    figObj =
    	figure

    Thanks for all the hard work,

    Donn

  2. Ondrej Konopka says:

    Hi Yair, I found out additional features in R2008b. Meanings of features are obvious from names of features in case of features with capital letters. The rest of features i have no idea what it does.

    feature(‘alloclist‘)
    feature(‘CachePath‘)
    feature(‘CheckMallocClear‘)
    feature(‘CheckMallocDispTaggedCallSite‘)
    feature(‘CheckMallocEnableAsserts‘)
    feature(‘CheckMallocLogTaggedCallSites‘)
    feature(‘CheckMallocLog‘)
    feature(‘CheckMallocNumStackFrames‘)
    feature(‘CheckMallocTagCallSites‘)
    feature(‘CheckMemoryIntegrity‘)
    feature(‘ClearMemoryStats‘)
    feature(‘ClearPcodeStats‘)
    feature(‘CoreDump‘)
    feature(‘DirectoryFreeze‘)
    feature(‘DirectoryUnfreeze‘)
    feature(‘DirsAddedUnfreeze‘)
    feature(‘DumpHeap‘)
    feature(‘InteruptLongjumps‘)
    feature(‘IsDMLWorker‘)
    feature(‘LogAllStreams‘)
    feature(‘logfile‘)
    feature(‘pallalloc‘)
    feature(‘pallleaks‘)
    feature(‘pclalloc‘)
    feature(‘pclleaks‘)
    feature(‘pcovclear‘)
    feature(‘pcovdisable‘)
    feature(‘pcovenable‘)
    feature(‘pcovisrunning‘)
    feature(‘pcovsavedata‘)
    feature(‘pcovsetfilename‘)
    feature(‘plogprint‘)
    feature(‘pnewalloc‘)
    feature(‘pnewleaks‘)
    feature(‘PrintMemoryCacheStats‘)
    feature(‘PrintMemoryStats‘)
    feature(‘PrintPcodeStats‘)
    feature(‘prompt‘)
    feature(‘purify‘)
    feature(‘qclear‘)
    feature(‘qewait‘)
    feature(‘qsavefile‘)
    feature(‘qsave‘)
    feature(‘qstart‘)
    feature(‘qstop‘)
    feature(‘quantify‘)
    feature(‘TestUDD‘)
    feature(‘uddcount‘)
    feature(‘valgrind‘)
    feature(‘vlogprint‘)
    feature(‘vnewleaks‘)

    Hopefully, it helps you improve these pages. Thanks for the hard work as well.

    Ondrej

  3. Yves Piguet says:

    Is this one known?

    feature list

    Try

    l = feature('list');
    for i = 1:length(l)
      fprintf('%35s has_cb=%d has_bi=%d calls=%d val=%g\n', ...
        l(i).name, l(i).has_callback, l(i).has_builtin, l(i).call_count, l(i).value);
    end
  4. Aurélien says:

    Reading this bug report this morning : MATLAB crashes during debugging
    http://www.mathworks.com/support/bugreports/595677
    I discovered other feature commands and of cours I immediately think about sharing this on your blog :

    1. Turn off the JIT in the offending program file using the command “feature scopedAccelEnablement off”.
    2. Turn off the jitting of structures using the command “feature jitallow structs off”.
    3. Turn off the JIT completely using the command “feature accel off”

  5. Pingback: Converting Java vectors to Matlab arrays | Undocumented Matlab

  6. Pingback: Profiling Matlab memory usage | Undocumented Matlab

  7. damayi says:

    Can you tell me what is the difference between feature(‘IsDebug’) and feature(‘IsDebugMode’);
    What’s more, I found that feature(‘IsDebugMode’) will always get false result when you run it in you m code, but in debug command, you can get true. why?

  8. Alexander says:

    You could also add: system_dependent(7) which toggles command window text buffering. It can help if you output very large strings.

    Btw, is there a way to query the current state? Or set it to on/off (not just toggle)? I.e. I don’t want to toggle it on and off – I just want to turn that off once.

  9. Rye says:

    I found this feature while trying to debug a bizarre error I was having with a GPU function:

    feature('GpuAllocPoolSizeKb')

    found this here: http://www.mathworks.com/matlabcentral/answers/28500

  10. Pingback: Using Java 7 in Matlab R2013a and earlier | Undocumented Matlab

  11. Pingback: Undocumented feature list | Undocumented Matlab

  12. Holger Krause says:

    Matlab running on linux uses server-side font rendering. In case, the server doesn’t provide requested fonts, text in figures is rendered in a default font, and changes in fontsize are without effect. This can be overcome with:

    feature('javadrawingmethods',2)

    In this mode, java seems to do the text rendering wihout relying on Xservers capabilities.

    Tested in R2014a and R2013a.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

<pre lang="matlab">
a = magic(3);
sum(a)
</pre>