PropertiesFile.rst 34.5 KB
Newer Older
1
2
.. _Properties File:

3
Properties File
4
5
===============

6
7
The ``*.properties`` Files
--------------------------
8

9
The Mantid framework is configured using up to three simple text ``*.properties`` files that are read an interpreted every time the framework is started. These properties are not the same as the properties of algorithms. All three have the same format. The three files are read from first to last, with the values in subsequent ``*.properties`` overriding those in previous ones.
10

11
12
1. Install directory ``Mantid.properties`` defines the default configuration that the development team suggest as sensible defaults. This file should not be altered by users as it will be replaced with every new install or upgrade of Mantid.
2. ``/etc/mantid.local.properties`` is an optional, linux only file that sets shared defaults on a shared system. This is commonly used for setting the ``default.facility``, ``default.instrument``, and ``datasearch.searcharchive`` properties.
13
3. Home directory ``Mantid.user.properties`` is where users may override any property setting in Mantid. Any Property setting in this file will override anything set in the ``Mantid.properties`` file. Simply either enter the property you wish to override in this file together with it's new value. The change will take effect the next time Mantid is started. Subsequent installs or upgrades of Mantid will never alter this file.
14

15
16
17
18
19
20
The user properties file, ``Mantid.user.properties``, can be found

* windows: ``$MantidInstallDirectory\bin\Mantid.user.properties``
* linux and mac-os: ``$HOME/.mantid/Mantid.user.properties``


21
22
23
The Properties
--------------

24
25
.. note:: Use forward slash (``/``) or double up on the number of backslash (``\``) characters for all paths

26

27
28
29
.. note:: Boolean properties evaluate ``true``, ``1``, and ``on`` (case insensitive) as ``true``, all other values as ``false``.


30
31
32
General properties
******************

33
34
35
36
37
38
39
40
41
42
43
44
45
46
+----------------------------------+--------------------------------------------------+------------------------+
|Property                          |Description                                       | Example value          |
+==================================+==================================================+========================+
| ``algorithms.categories.hidden`` | A comma separated list of any categories of      | ``Muons,Testing``      |
|                                  | algorithms that should be hidden in Mantid.      |                        |
+----------------------------------+--------------------------------------------------+------------------------+
| ``curvefitting.guiExclude``      | A semicolon separated list of function names     | ``ExpDecay;Gaussian;`` |
|                                  | that should be hidden in Mantid.                 |                        |
+----------------------------------+--------------------------------------------------+------------------------+
| ``MultiThreaded.MaxCores``       | Sets the maximum number of cores available to be | ``0``                  |
|                                  | used for threads for                             |                        |
|                                  | `OpenMP <http://www.openmp.org/>`_. If zero it   |                        |
|                                  | will use one thread per logical core available.  |                        |
+----------------------------------+--------------------------------------------------+------------------------+
47
48
49
50

Facility and instrument properties
**********************************

51
52
53
54
+------------------------------+----------------------------------------------------+---------------------+
|Property                      |Description                                         |Example value        |
+==============================+====================================================+=====================+
| ``default.facility``         | The name of the default facility. The facility     | ``ISIS``            |
55
|                              | must be defined within the facilities.xml file to  |                     |
56
57
58
59
60
61
62
63
64
65
66
67
|                              | be considered valid. The file is described         |                     |
|                              | :ref:`here <Facilities file>`.                     |                     |
+------------------------------+----------------------------------------------------+---------------------+
| ``default.instrument``       | The name of the default instrument. The instrument | ``WISH``            |
|                              | must be defined within the facilities.xml file to  |                     |
|                              | be valid. The file is described                    |                     |
|                              | :ref:`here <Facilities file>`.                     |                     |
+------------------------------+----------------------------------------------------+---------------------+
| ``Q.convention``             | The convention for converting to Q. For            | ``Crystallography`` |
|                              | ``Inelastic`` the convention is ki-kf.  For        | or ``Inelastic``    |
|                              | ``Crystallography`` the convention is kf-ki.       |                     |
+------------------------------+----------------------------------------------------+---------------------+
68
69
70
71

Directory Properties
********************

72
73
74
+--------------------------------------+---------------------------------------------------+-------------------------------------+
|Property                              |Description                                        |Example value                        |
+======================================+===================================================+=====================================+
75
76
| ``colormaps.directory``              | The directory where colormaps are located         | ``/opt/mantid/colormaps``           |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
77
78
79
80
81
82
83
84
85
86
87
| ``datasearch.directories``           | A semi-colon(``;``) separated list of directories | ``../data;\\\\isis\\isis$\\ndxgem`` |
|                                      | to use to search for data.                        |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``datasearch.searcharchive``         | ``on`` (only the default facility), ``off``       | ``on`` or ``hfir,sns``              |
|                                      | (none), ``all`` (all archives), or a list of      |                                     |
|                                      | individual facilities to search for files in the  |                                     |
|                                      | data archive                                      |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``defaultsave.directory``            | A default directory to use for saving files.      | ``../data``                         |
|                                      | the data archive                                  |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
88
89
90
91
92
93
| ``framework.plugins.directory``      | The path to the directory that contains the       | ``../plugins``                      |
|                                      | Mantid plugin libraries                           |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``framework.plugins.exclude``        | A list of substrings to allow libraries to be     | ``Qt4;Qt5``                         |
|                                      | skipped                                           |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
94
95
| ``instrumentDefinition.directory``   | Where to load instrument definition files from    | ``../Test/Instrument``              |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
96
97
98
| ``mantidqt.plugins.directory``       | The path to the directory containing the          | ``../plugins/qtX``                  |
|                                      | Mantid Qt-based plugin libraries                  |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
| ``parameterDefinition.directory``    | Where to load parameter definition files from     | ``../Test/Instrument``              |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``pythonscripts.directories``        | Python will also search the listed directories    | ``../scripts`` or ``C:/MyScripts``  |
|                                      | when importing modules.                           |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``pythonscripts.directory``          | **DEPRECATED:** Use ``pythonscripts.directories`` | N/A                                 |
|                                      | instead                                           |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``requiredpythonscript.directories`` | A list of directories containing Python scripts   | N/A                                 |
|                                      | that Mantid requires to function correctly.       |                                     |
|                                      | **WARNING:** Do not alter the default value.      |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
| ``requiredpythonscript.directories`` | A list of directories containing Python scripts   | N/A                                 |
|                                      | that Mantid requires to function correctly.       |                                     |
|                                      | **WARNING:** Do not alter the default value.      |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
115
116
117
118
119
| ``python.plugins.manifest``          | A path to the location of the manifest file       | N/A                                 |
|                                      | containing paths to each of the python algorithm  |                                     |
|                                      | files.                                            |                                     |
|                                      | **WARNING:** Do not alter the default value.      |                                     |
+--------------------------------------+---------------------------------------------------+-------------------------------------+
120
121
122
123
124


Logging Properties
******************

125
126
127
128
129
130
131
132
133
The details of configuring the logging functionality within Mantid will not be explained here. For those who want more
details look into the `POCO logging classes <https://pocoproject.org/docs/package-Foundation.Logging.html>`_ and the
`Log4J logging module <https://logging.apache.org/log4j/>`_ that it closely emulates. There are several comments in the
properties file itself that explain the configuration we provide by default.  However there are some obvious areas that
you may want to alter and those properties are detailed below.

+-------------------------------------------------+---------------------------------------------------+-----------------------------+
|Property                                         |Description                                        |Example value                |
+=================================================+===================================================+=============================+
134
135
136
| ``logging.loggers.root.level``                  |Defines the level of messages to be output         | ``debug``, ``information``, |
|                                                 |by the system.                                     | ``notice``, ``warning``,    |
|                                                 |The default is information, but                    | ``error``, ``critical``     |
137
138
|                                                 |this can be lowered to debug for more detailed     | or ``fatal``                |
|                                                 |feedback.                                          |                             |
139
140
141
142
143
144
145
+-------------------------------------------------+---------------------------------------------------+-----------------------------+
| ``logging.channels.consoleChannel.class``       | Select where log messages appear.                 | ``ConsoleChannel``,         |
|                                                 | ``ConsoleChannel`` writes to stdlog.              | ``StdoutChannel``, or       |
|                                                 | ``StdoutChannel`` writes to stdout and can be     | ``PythonStdoutChannel``     |
|                                                 | redirected using pipes.                           |                             |
|                                                 | ``PythonStdoutChannel`` writes to stdout through  |                             |
|                                                 | python and is visible in jupyter notebooks.       |                             |
146
+-------------------------------------------------+---------------------------------------------------+-----------------------------+
147

148
The logging priority levels for the file logging and console logging can also be adjusted in python using the command:
149
150
151

.. testcode:: LoggingConfigExample

152
153
154
155
  #Set the log to debug level or above (7=debug)
  ConfigService.setLogLevel(7)
  #Set the log to critical level (2=critical)
  ConfigService.setLogLevel(2)
156

157

158

159
160
Mantid Graphical User Interface Properties
******************************************
161

162
163
164
+--------------------------------------------+---------------------------------------------------+-----------------+
|Property                                    |Description                                        |Example value    |
+============================================+===================================================+=================+
165
166
167
| ``Notifications.Enabled``                  |Should Mantid use System Notifications for         | ``On``, ``Off`` |
|                                            |important messages?                                |                 |
+--------------------------------------------+---------------------------------------------------+-----------------+
168
| ``cluster.submission``                     |Enable cluster submission elements in GUIs         | ``On``, ``Off`` |
169
170
171
172
+--------------------------------------------+---------------------------------------------------+-----------------+
| ``MantidOptions.InstrumentView.UseOpenGL`` |Controls the use of OpenGL in rendering the        | ``On``, ``Off`` |
|                                            |"unwrapped" (flat) instrument views.               |                 |
+--------------------------------------------+---------------------------------------------------+-----------------+
173
| ``MantidOptions.InvisibleWorkspaces``      |Do not show 'invisible' workspaces                 | ``0``, ``1``    |
174
+--------------------------------------------+---------------------------------------------------+-----------------+
175
| ``PeakColumn.hklPrec``                     |Precision of hkl values shown in tables            | ``2``           |
176
177
+--------------------------------------------+---------------------------------------------------+-----------------+

178

179
180
181
Network Properties
******************

182
183
184
+-------------------------------------------+---------------------------------------------------+---------------------------------+
|Property                                   |Description                                        |Example value                    |
+===========================================+===================================================+=================================+
185
186
| ``catalog.timeout.value``                 | Network timeout for ICAT4 requests                | ``30``                          |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
187
188
189
| ``CheckMantidVersion.OnStartup``          | Check if there is a newer version available and   |                                 |
|                                           | logs a message at ``information`` level           | ``1``                           |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
190
191
192
| ``ISISDAE.Timeout``                       | Timeout for network requests when reading live    |  ``100``                        |
|                                           | data from ISIS (in seconds)                       |                                 |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
193
194
195
196
| ``network.default.timeout``               |Defines the default timeout for all network        | ``30``                          |
|                                           |operations (in seconds).                           |                                 |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
| ``network.scriptrepo.timeout``            |The timeout for network operations in the script   | ``5``                           |
197
|                                           |repository, this overrides the default timeout.    |                                 |
198
+-------------------------------------------+---------------------------------------------------+---------------------------------+
199
200
201
202
| ``network.github.api_token``              |The api token for github calls used by             | (not shown)                     |
|                                           |``DownloadInstrument``. Setting this to ``unset``  |                                 |
|                                           |or an empty string will turn off authentication.   |                                 |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
| ``proxy.host``                            | Allows the system proxy to be overridden, if not  | ``http://www.proxy.org``        |
|                                           | set mantid will use the system proxy              |                                 |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
| ``proxy.port``                            | Must be set if proxy.host is set                  | ``8080``                        |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
| ``proxy.httpsTargetUrl``                  | A sample url used to determine the system proxy to| ``http://www.google.com``       |
|                                           | use on windows.                                   |                                 |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
| ``UpdateInstrumentDefinitions.OnStartup`` | Download new instrument definition files and      |                                 |
|                                           | ``Facilities.xml`` to ``~/.mantid/instruments``   |                                 |
|                                           | on linux or ``APPDATA`` directory on windows. If  |                                 |
|                                           | this is disabled, previously downloaded           |                                 |
|                                           | instruments are ignored and only those in the     |                                 |
|                                           | installation are used.                            | ``1``                           |
+-------------------------------------------+---------------------------------------------------+---------------------------------+
| ``usagereports.enabled``                  | Enable usage reporting                            | ``1``                           |
+-------------------------------------------+---------------------------------------------------+---------------------------------+

221

222
223
224
ScriptRepository Properties
***************************

225
226
227
228
229
+----------------------------+-----------------------------------------------+----------------------------------------------------------------------+
|Property                    |Description                                    |Example value                                                         |
+============================+===============================================+======================================================================+
| ``ScriptLocalRepository``  |Directory where ScriptRepository is Installed. | ``C:\\MantidInstall\\MyScriptRepository``                            |
+----------------------------+-----------------------------------------------+----------------------------------------------------------------------+
230
| ``ScriptRepository``       |Base URL for the remote script repository.     | ``https://download.mantidproject.org/scriptrepository/``             |
231
232
233
234
+----------------------------+-----------------------------------------------+----------------------------------------------------------------------+
| ``ScriptRepositoryIgnore`` |CSV patterns for paths that should not be      | ``*pyc;``                                                            |
|                            |listed at ScriptRepository.                    |                                                                      |
+----------------------------+-----------------------------------------------+----------------------------------------------------------------------+
235
| ``UploaderWebServer``      |URL for uploading scripts.                     | ``https://upload.mantidproject.org/scriptrepository/payload/publish``|
236
+----------------------------+-----------------------------------------------+----------------------------------------------------------------------+
237
238


239
240
241
Project Recovery
****************

Peterson, Peter's avatar
Peterson, Peter committed
242
See :ref:`project recovery <Project Recovery>` for more details.
243
244
245
246
247
248
249
250
251
252
253

+-----------------------------------------+-----------------------------------------------+------------------+
|Property                                 |Description                                    |Example value     |
+=========================================+===============================================+==================+
| ``projectRecovery.enabled``             |Whether project recovery is enabled            |  ``On``, ``Off`` |
+-----------------------------------------+-----------------------------------------------+------------------+
| ``projectRecovery.numberOfCheckpoints`` |How many checkpoints/backups to keep           | ``5``            |
+-----------------------------------------+-----------------------------------------------+------------------+
| ``projectRecovery.secondsBetween``      |How often to save checkpoints in seconds       | ``60``           |
+-----------------------------------------+-----------------------------------------------+------------------+

254
255
256
257
258
259
260
261
262
Project Saving
**************

+---------------------------------+------------------------------------------------------------------+------------------+
|Property                         |Description                                                       |Example value     |
+=================================+==================================================================+==================+
| ``projectSaving.warningSize``   |Size in bytes of a project before the user is warned when saving  |  ``10737418240`` |
+---------------------------------+------------------------------------------------------------------+------------------+

263
264
265
266
267
268
269
270
Plotting Settings
*****************

+---------------------------------+------------------------------------------------------------------+---------------------+
|Property                         |Description                                                       |Example value        |
+=================================+==================================================================+=====================+
|``plots.ShowTitle``              |Whether to show titles on plots                                   | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
StephenSmith25's avatar
StephenSmith25 committed
271
|``plots.ShowLegend``             |Whether to show legend on plots                                   | ``On``, ``Off``     |
272
+---------------------------------+------------------------------------------------------------------+---------------------+
273
274
|``plots.font``                   |The default font for labels and titles on plots.                  |``Helvetica``        |
+---------------------------------+------------------------------------------------------------------+---------------------+
275
276
277
278
|``plots.xAxesScale``             |The default x scale on 1d plots                                   |``Linear``, ``Log``  |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.yAxesScale``             |The default y scale on 1d plots                                   |``Linear``, ``Log``  |
+---------------------------------+------------------------------------------------------------------+---------------------+
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
|``plots.axesLineWidth``          |The default width of the lines that make the axes                 |``1``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.enableGrid``             |The default y scale on 1d plots                                   |``Linear``, ``Log``  |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ShowMinorTicks``         |Whether to show minor ticks on plots                              | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ShowMinorGridlines``     |Whether to show minor gridlines on plots                          | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showTicksLeft``          |Whether to show ticks on the left side of the plot                | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showTicksBottom``        |Whether to show ticks on the bottom of the plot                   | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showTicksRight``         |Whether to show ticks on the right side of the plot               | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showTicksTop``           |Whether to show ticks on the top side of the plot                 | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showLabelsLeft``         |Whether to show labels on the left side of the plot               | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showLabelsBottom``       |Whether to show labels on the bottom of the plot                  | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showLabelsRight``        |Whether to show labels on the right side of the plot              | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.showLabelsTop``          |Whether to show labels on the top side of the plot                | ``On``, ``Off``     |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.major.length``     |The default length of the major ticks                             |``6``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.major.width``      |The default width of the major ticks                              |``1``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.major.direction``  |The default direction of the major ticks                          |``In``, ``Out``,     |
|                                 |                                                                  |``InOut``            |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.minor.length``     |The default length of the minor ticks                             |``3``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.minor.width``      |The default width of the minor ticks                              |``1``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.ticks.minor.direction``  |The default direction of the minor ticks                          |``In``, ``Out``,     |
|                                 |                                                                  |``InOut``            |
+---------------------------------+------------------------------------------------------------------+---------------------+
317
318
|``plots.line.Style``             |Default Line style on 1d plots                                    |``solid``, ``dashed``|
+---------------------------------+------------------------------------------------------------------+---------------------+
Stephen's avatar
Stephen committed
319
320
|``plots.line.DrawStyle``         |Default Draw style on 1d plots                                    |``default``,``steps``|
+---------------------------------+------------------------------------------------------------------+---------------------+
321
322
323
324
325
326
|``plots.line.Width``             |Default Line width on 1d plots                                    |``1.5``              |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.marker.Style``           |Default marker style on 1d plots                                  |``point``            |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.marker.Size``            |Default maker size on 1d plots                                    |``6``                |
+---------------------------------+------------------------------------------------------------------+---------------------+
327
|``plots.errorbar.Capsize``       |Default cap size on error bars in 1d plots                        |``1.0``              |
328
329
330
331
332
333
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.errorbar.CapThickness``  |Default cap thickness on error bars in 1d plots                   |``1.0``              |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.errorbar.errorEvery``    |Default number of error bars for every data point                 |``1``                |
|                                 |in 1d plots. Must be an integer                                   |                     |
+---------------------------------+------------------------------------------------------------------+---------------------+
334
|``plots.errorbar.Width``         |Default width of error bars in 1d plots                           |``1.0``              |
335
+---------------------------------+------------------------------------------------------------------+---------------------+
336
337
338
339
|``plots.legend.FontSize``        |Default legend font size                                          |``8.0``              |
+---------------------------------+------------------------------------------------------------------+---------------------+
|``plots.legend.Location``        |Default legend location                                           |``best``             |
+---------------------------------+------------------------------------------------------------------+---------------------+
340
|``plots.images.Colormap``        |Default colormap for image plots                                  |``viridis``          |
341
+---------------------------------+------------------------------------------------------------------+---------------------+
Stephen's avatar
Stephen committed
342
343
|``plots.images.ColorBarScale``   |Default colorbar scale for image plots                            |``Linear``           |
+---------------------------------+------------------------------------------------------------------+---------------------+
344

345
346
347
348
349
350
351
352
353
Getting access to Mantid properties
***********************************

To get access to, e.g. data saving path property from a C++ program one has to issue the following command:


.. testcode:: properties

  path = ConfigService.getString("defaultsave.directory")
354

355
.. categories:: Concepts