MatRad_Config

0001 classdef MatRad_Config < handle
0002 % MatRad_Config MatRad Configuration class
0003 % This class is used globally through Matlab to handle default values and
0004 % logging and is declared as global matRad_cfg.
0005 % Usage:
0006 %    matRad_cfg = MatRad_Config.instance();
0007 %
0008 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0009 %
0010 % Copyright 2019 the matRad development team.
0011 %
0012 % This file is part of the matRad project. It is subject to the license
0013 % terms in the LICENSE file found in the top-level directory of this
0014 % distribution and at https://github.com/e0404/matRad/LICENSES.txt. No part
0015 % of the matRad project, including this file, may be copied, modified,
0016 % propagated, or distributed except according to the terms contained in the
0017 % LICENSE file.
0018 %
0019 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0020 
0021     
0022     properties
0023 
0024         %Logging
0025         logLevel = 3; %1 = only Errors, 2 = with Warnings, 3 = Info output, 4 = deprecation warnings, 5 = debug information
0026         keepLog = false; %Stores the full log in memory
0027         writeLog = false; %Writes the log to a file on-the-fly
0028         
0029         %Default Properties
0030         propDoseCalc;
0031         propOpt;
0032         propMC;
0033         propStf;
0034         
0035         %Disable GUI
0036         disableGUI = false;
0037     end
0038     
0039     properties (SetAccess = private)
0040         messageLog = {};
0041         logFileHandle;
0042         
0043         %For storing the Environment & its version
0044         env;
0045         envVersion;
0046         isOctave; %Helper bool to check for Octave
0047         isMatlab; %Helper bool to check for Matlab
0048     end
0049     
0050     properties (Constant)
0051         matRadRoot = fileparts(mfilename('fullpath'));
0052     end
0053     
0054     methods (Access = private)
0055         function obj = MatRad_Config()
0056             %MatRad_Config Constructs an instance of this class.
0057             %  The configuration is implemented as a singleton and used globally
0058             %  Therefore its constructor is private
0059             %  For instantiation, use the static MatRad_Config.instance();
0060             
0061             %Set Version
0062             obj.getEnvironment();
0063             
0064             %Just to catch people messing with the properties in the file
0065             if ~isempty(obj.writeLog) && obj.writeLog
0066                 logFile = [matRadRoot filesep 'matRad.log'];
0067                 obj.logFileHandle = fopen(logFile,'a');
0068             end
0069             
0070             %Call the reset function for remaining inatialization
0071             obj.reset();
0072         end
0073         
0074         function displayToConsole(obj,type,formatSpec,varargin)
0075             %displayToConsole lowest-level logging function for matRad.
0076             %   Display to console will be called from the public wrapper
0077             %   functions dispError, dispWarning, dispInfo, dispDebug
0078             %
0079             %  input
0080             %    type:            type of the log information.
0081             %                   Needs to be one of 'error', 'warning', 'info' or 'debug'.
0082             %    formatSpec:     string to print using format specifications similar to fprintf
0083             %    varargin:       variables according to formatSpec
0084             
0085             if nargin < 4
0086                 forwardArgs = {formatSpec};
0087             else
0088                 forwardArgs = [{formatSpec},varargin(:)'];
0089             end
0090             
0091             if obj.keepLog
0092                 obj.messageLog{end+1,1} = upper(type);
0093                 obj.messageLog{end,2} = sprintf(forwardArgs{:});
0094             end
0095             
0096             switch type
0097                 case{'info'}
0098                     if obj.logLevel >= 3
0099                         fprintf(forwardArgs{:});
0100                     end
0101                 case{'debug'}
0102                     if obj.logLevel >= 5
0103                         forwardArgs{1} = ['DEBUG: ' forwardArgs{1}];
0104                         fprintf(forwardArgs{:});
0105                     end
0106                 case{'dep'}
0107                     if obj.logLevel >= 4
0108                         forwardArgs{1} = ['DEPRECATION WARNING: ' forwardArgs{1}];
0109                         warning(forwardArgs{:});
0110                     end
0111                 case{'warning'}
0112                     if obj.logLevel >= 2
0113                         warning(forwardArgs{:});
0114                     end
0115                 case {'error'}
0116                     if obj.logLevel >= 1
0117                         %We create an error structure to later clean the
0118                         %stack trace from the last two files/lines (i.e.,
0119                         %this function / file)
0120                         
0121                         err.message = sprintf(forwardArgs{:});
0122                         err.identifier = 'matRad:Error';
0123                         err.stack = dbstack(2);
0124                         error(err);
0125                         
0126                     end
0127                 otherwise
0128                     error('Log type %s not defined!',type);
0129             end
0130             
0131             if obj.writeLog
0132                 fprintf(obj.logFileHandle,forwardArgs{:});
0133             end
0134         end
0135         
0136     end
0137     
0138     methods
0139         function reset(obj)
0140             %Set all default properties for matRad's computations
0141             obj.setDefaultProperties();
0142         end
0143         
0144         function setDefaultProperties(obj)
0145             %setDefaultProperties set matRad's default computation
0146             %   properties
0147             %  input
0148             
0149             obj.propStf.defaultLongitudinalSpotSpacing = 3;
0150             obj.propStf.defaultAddMargin = true; %expand target for beamlet finding
0151             
0152             obj.propDoseCalc.defaultResolution = struct('x',3,'y',3,'z',3); %[mm]
0153             obj.propDoseCalc.defaultLateralCutOff = 0.995; %[rel.]
0154             obj.propDoseCalc.defaultGeometricCutOff = 50; %[mm]
0155             obj.propDoseCalc.defaultSsdDensityThreshold = 0.05; %[rel.]
0156             obj.propDoseCalc.defaultUseGivenEqDensityCube = false; %Use the given density cube ct.cube and omit conversion from cubeHU.
0157             obj.propDoseCalc.defaultIgnoreOutsideDensities = true; %Ignore densities outside of cst contours
0158             obj.propDoseCalc.defaultUseCustomPrimaryPhotonFluence = false; %Use a custom primary photon fluence
0159             
0160             obj.propOpt.defaultMaxIter = 500;
0161             
0162             obj.propMC.ompMC_defaultHistories = 1e6;
0163             obj.propMC.ompMC_defaultOutputVariance = false;
0164             obj.propMC.MCsquare_defaultHistories = 1e6;
0165             obj.propMC.direct_defaultHistories = 2e4;
0166             
0167             obj.disableGUI = false;
0168         end
0169         
0170         %%For testing
0171         function setDefaultPropertiesForTesting(obj)
0172             %setDefaultPropertiesForTesting sets matRad's default
0173             %properties during testing to reduce computational load
0174             
0175             obj.logLevel   = 1; %Omit output except errors
0176             
0177             obj.propStf.defaultLongitudinalSpotSpacing = 20;
0178             obj.propStf.defaultAddMargin = true; %expand target for beamlet finding
0179             
0180             obj.propDoseCalc.defaultResolution = struct('x',5,'y',6,'z',7); %[mm]
0181             obj.propDoseCalc.defaultGeometricCutOff = 20;
0182             obj.propDoseCalc.defaultLateralCutOff = 0.8;
0183             obj.propDoseCalc.defaultSsdDensityThreshold = 0.05;
0184             obj.propDoseCalc.defaultUseGivenEqDensityCube = false; %Use the given density cube ct.cube and omit conversion from cubeHU.
0185             obj.propDoseCalc.defaultIgnoreOutsideDensities = true;
0186             obj.propDoseCalc.defaultUseCustomPrimaryPhotonFluence = false; %Use a custom primary photon fluence
0187             
0188             obj.propOpt.defaultMaxIter = 10;
0189             
0190             obj.propMC.ompMC_defaultHistories = 100;
0191             obj.propMC.ompMC_defaultOutputVariance = true;
0192             obj.propMC.MCsquare_defaultHistories = 100;
0193             obj.propMC.direct_defaultHistories = 100;
0194             
0195             obj.disableGUI = true;
0196         end
0197         
0198         function dispDebug(obj,formatSpec,varargin)
0199             %dispDebug print debug messages (log level >= 4)
0200             %  input
0201             %    formatSpec:     string to print using format specifications similar to fprintf
0202             %    varargin:       variables according to formatSpec
0203             
0204             obj.displayToConsole('debug',formatSpec,varargin{:});
0205         end
0206         
0207         function dispInfo(obj,formatSpec,varargin)
0208             %dispInfo print information console output (log level >= 3)
0209             %  input
0210             %    formatSpec:     string to print using format specifications similar to fprintf
0211             %    varargin:       variables according to formatSpec
0212             obj.displayToConsole('info',formatSpec,varargin{:});
0213         end
0214         
0215         function dispError(obj,formatSpec,varargin)
0216             %dispError print errors (forwarded to "error" that will stop the program) (log level >= 1)
0217             %  input
0218             %    formatSpec:     string to print using format specifications
0219             %                   similar to 'error'
0220             %    varargin:       variables according to formatSpec
0221             obj.displayToConsole('error',formatSpec,varargin{:});
0222         end
0223         
0224         function dispWarning(obj,formatSpec,varargin)
0225             %dispError print warning (forwarded to 'warning') (log level >= 2)
0226             %  input
0227             %    formatSpec:     string to print using format specifications
0228             %                   similar to 'warning'
0229             %    varargin:       variables according to formatSpec
0230             obj.displayToConsole('warning',formatSpec,varargin{:});
0231         end
0232         
0233         function dispDeprecationWarning(obj,formatSpec,varargin)
0234             %dispDeprecationWarning wrapper for deprecation warnings forwarded to displayToConsole
0235             obj.displayToConsole('dep',formatSpec,varargin{:});
0236         end
0237         
0238         function obj = writeLogToFile(obj,filename)
0239             %writeLogToFile writes the log kept in MatRad_Config to file.
0240             %  Note that the switch keepLog must be enabled for MatRad_Config to store all logging output.
0241             
0242             singleString = '%s: %s\n';
0243             fID = fopen(filename,'w');
0244             fprintf(fID,repmat(singleString,1,size(obj.messageLog,1)),obj.messageLog{:});
0245             fclose(fID);
0246         end
0247         
0248         function set.logLevel(obj,newLogLevel)
0249             %%Property set methods for logLevel
0250             minLevel = 1;
0251             maxLevel = 5;
0252             if newLogLevel >= minLevel && newLogLevel <= maxLevel
0253                 obj.logLevel = newLogLevel;
0254             else
0255                 obj.dispError('Invalid log level. Value must be between %d and %d',minLevel,maxLevel);
0256             end
0257         end
0258         
0259         function set.writeLog(obj,writeLog)
0260             if writeLog
0261                 logFile = [obj.matRadRoot filesep 'matRad.log'];
0262                 obj.logFileHandle = fopen(logFile,'a');
0263                 obj.writeLog = true;
0264             else
0265                 fclose(obj.logFileHandle);
0266                 obj.writeLog = false;
0267             end
0268         end
0269         
0270         function getEnvironment(obj)
0271             % getEnvironment function to get the software environment
0272             %   matRad is running on
0273             
0274             obj.isOctave = exist('OCTAVE_VERSION', 'builtin') ~= 0;
0275             obj.isMatlab = ~obj.isOctave;
0276             
0277             if obj.isOctave
0278                 obj.env = 'OCTAVE';
0279                 obj.envVersion = OCTAVE_VERSION;
0280             else
0281                 obj.env = 'MATLAB';
0282                 vData = ver(obj.env);
0283                 obj.envVersion = vData.Version;
0284                 
0285             end
0286         end
0287     end
0288     
0289     methods(Static)
0290         
0291         function obj = instance()
0292             %instance creates a singleton instance of MatRad_Config
0293             %  In MatRad_Config, the constructor is private to make sure only on global instance exists.
0294             %  Call this static functino to get or create an instance of the matRad configuration class
0295             persistent uniqueInstance;
0296             
0297             if isempty(uniqueInstance)
0298                 obj = MatRad_Config();
0299                 uniqueInstance = obj;
0300             else
0301                 obj = uniqueInstance;
0302             end
0303         end
0304     end
0305 end
0306