Skip to main content

Infer.NET user guide : Running inference

Inference engine settings

High-level inference settings are all accessed via properties or methods of an InferenceEngine object (in the Microsoft.ML.Probabilistic namespace). The settings take effect at the point of model compilation; typically this occurs when you request a marginal value from one of your variables, at which point both model compilation and inference occur. However, you can separate out compilation and inference as discussed in Controlling how inference is performed.

You can get an instance of the InferenceEngine class via the following snippet:

InferenceEngine engine = new InferenceEngine();


This setting specifies the inference engine that will be used. Working with different inference algorithms describes this option in more detail. The options currently are:

// Use Expectation propagation  
engine.Algorithm = new ExpectationPropagation();
// Use Variational Message Passing  
engine.Algorithm = new VariationalMessagePassing();
// Use Gibbs sampling  
engine.Algorithm = new GibbsSampling();

The default setting for the algorithm is Expectation Propagation. You can also optionally specify the algorithm when you create the engine:

InferenceEngine engine = new InferenceEngine(new VariationalMessagePassing());


This property holds the compiler that the inference engine uses to compile the model into efficient inference code. You cannot modify this property but you can modify properties of the returned ModelCompiler object as described in the table below.

Property Description and example Default value
GeneratedSourceFolder The relative or absolute path of the folder where the C# inference source code should be generated. engine.Compiler.GeneratedSourceFolder = "MyGeneratedSourceFolder"; “GeneratedSource”
WriteSourceFiles Specifies whether the generated source code should be written to disk.

To prevent writing source files to disk, so that instead they are only generated in memory, use: engine.Compiler.WriteSourceFiles = false;
GenerateInMemory Specifies whether the inference assembly should be generated in memory or on disk. Generating the assembly in memory can avoid security exceptions if you are running your inference from a network drive. If you want to debug into your generated inference code, you must set this to false: engine.Compiler.GenerateInMemory = false; true
IncludeDebugInformation Specifies whether the inference assembly should be compiled with debugging symbols. If you want to debug into your generated inference code, you must set this to true: engine.Compiler.IncludeDebugInformation = true; false
ReturnCopies If true, code will be generated to return copies of the internal marginal distributions. If this is not done, modifying returned marginals in place may affect the result of future inference calculations. Even when set to true, the copying is only done during inference; when Infer returns a cached result, this will be the same object previously returned.

If you want to save memory by avoiding creating these copies, you can set this to false: engine.Compiler.ReturnCopies = false;
FreeMemory If true, internal message arrays will be freed and re-allocated every time inference is run. This minimizes the memory overhead of inference. If false, internal message arrays will be kept alive between runs. To speed up inference when running the same model many times with different data, you can set this to false: engine.Compiler.FreeMemory = false; true
AddComments If true, the generated code will contain comments describing each statement. To reduce the size of the generated code, you can set this to false. true
OptimiseInferenceCode If true, various optimisations will be applied to the generated inference code which normally result in significant speed ups and reduction in memory usage.

You should generally never set this to false - this option is provided to help with debugging of these new optimisation features. The only circumstance where you may try setting this to false is if the compiler fails in an optimisation transform. If you have an example which only works without optimisation, please report this to the Infer.NET team.
IgnoreEqualObserved ValuesForValueTypes Let’s you control what happens when you set an observed value which is equal to the old observed value for value types. If this property is true, setting an equal value will be ignored. If false, setting an equal value may cause inference to be re-run. true
IgnoreEqualObserved ValuesForReferenceTypes Let’s you control what happens when you set an observed value which is equal to the old observed value for reference types. If this property is true, setting an equal value will be ignored. If false, setting an equal value may cause inference to be re-run. false
RecommendedQuality Recommended quality band. The compiler will issue a warning for any component in your model which has a quality band below this level. QualityBand.Preview
RequiredQuality Required quality band. The compiler will raise an error for any component in your model which has a quality band below this level. QualityBand.Experimental
GivePriorityTo, PriorityList The compiler uses a search path when looking for factor implementations. This method allows you to move certain implementations to the front of the search path, thereby changing properties of the inference algorithm. The first factor implementation found when searching through loaded assemblies.
UseParallelForLoops If true, instructs the compiler to use multiple cores by emitting parallel ‘for’ loops rather than normal ‘for’ loops. false
UseSerialSchedules (experimental) If true, instructs the compiler to update variables in a sequential order (determined by Sequential attributes attached to ranges). See the Difficulty versus ability example.

This is an experimental feature and subject to change in future releases.
AllowSerialInitializers (experimental) Controls the schedule when UseSerialSchedules=true. Set this to false to reduce memory in exchange for more computation. Useful for large datasets that would otherwise run out of memory.

This is an experimental feature and subject to change in future releases.
BrowserMode Controls when the transform browser is shown. Never
CompilerChoice Selects the compiler used to compile the generated code: Roslyn or CodeDom.Compiler. CodeDom on .NET framework 4.6.1 or higher, otherwise Roslyn.


All the defaults specified on this page can modified by changing properties of DefaultEngine which is a static property of the InferenceEngine class. For example:

InferenceEngine.DefaultEngine.Algorithm = new VariationalMessagePassing();  
InferenceEngine.DefaultEngine.ShowFactorGraph = true;

These settings will then become the default settings when a new InferenceEngine instance is created.


Allows you to specify that a set of variables are in a group. This is currently only used to manually specify the blocks in Block Gibbs Sampling. Note that groupings are automatically determined as necessary, so it is not typically necessary for you to call this method; but this does give you a manual override. A list of variables is passed to this method; the first argument is the root variable in the block which determines the order of message passing within it (first marginalisation within the block occurs towards the root, and then sampling is done away from from the root). Here is an example for a product of two Gaussians:

Variable<double> a = Variable.GaussianFromMeanAndVariance(1, 2);  
Variable<double> b = Variable.GaussianFromMeanAndVariance(2, 3);  
Variable<double> c = a * b;  
GibbsSampling gs = new GibbsSampling();  
gs.BurnIn = 100; gs.Thin = 10;  
InferenceEngine engine = new InferenceEngine(gs);  
engine.NumberOfIterations = 10000;  
engine.Group(a, c);  
engine.Group(b, c);  
var marg = engine.Infer<Gaussian>(c);

ModelName and ModelNamespace

Allows a name to be specified for the model, which is used in the class name of the generated code. ModelName defaults to “Model” and ModelNamespace defaults to “Models”.

// Change the model name  
engine.ModelName = "MyMixtureModel";
// Change the model namespace
engine.ModelNamespace = "MyNamespace";


This specifies how many iterations the algorithm will run for. An ‘iteration’ is a single update of all the variables in a model. For the EP and VMP algorithms. only a handful of iterations are sometimes required, and the inference algorithm may converge well before the default number of 50 iterations for the two algorithms.

// Change the number of iterations  
engine.NumberOfIterations = 10;

Setting the number of iterations to -1 tells the inference engine to use the algorithm-specific default number of iterations. Note that Gibbs sampling will typically need many more iterations than EP or VMP.

This property can be used to do incremental inference. For example, suppose the NumberOfIterations is set to 10 and Infer() is called. Setting the NumberOfIterations to 20 and calling Infer() again will result in a further 10 iterations being executed. NumberOfIterations is effectively controlling the argument to Execute() on the underlying generated algorithm (see Controlling how inference is performed).


This property lets you specify a list of variables which the inference engine should optimise inference for. If you set this property, the inference engine will internally generate code for performing inference on exactly this set of variables, avoiding the overhead of computing or caching marginals for any other variables. If you set this property and then call Infer() on a variable not in this list, you will get an error.

// Optimise the engine to infer variables x, y and z. 
engine.OptimiseForVariables = new[] {x,y,z};

Setting this property to null reverts the engine to its normal behaviour where it will automatically choose which variables to perform inference on.


This option is useful for reducing the number of iterations required when observed values change. If true (the default), calling Infer() resets messages to their initial values if an observed value has changed. This ensures that the result of inference is always the same for the same set of observed values, but requires a full set of iterations to be performed each time. If false, the messages will not be reset when an observed value has changed. Thus the result of inference may depend on the previous observed values, but convergence can be faster. This option effectively switches between using Update instead of Execute on the underlying generated algorithm (see Controlling how inference is performed).

// Do not reset the message state  
engine.ResetOnObservedValueChanged = false;  

engine.NumberOfIterations = 10;  
// Perform 10 iterations from the initial state  
y.ObservedValue = 4;  
// Perform 10 additional iterations (since y has changed)  
// but from the current state  
engine.NumberOfIterations = 12;  
// Perform 2 additional iterations (since 10 already done  
// for the current y)  
engine.NumberOfIterations = 5;  
// Perform 5 additional iterations (since 5 < 12)  
// from the current message state  


This specifies whether to display the factor graph corresponding to the model. A factor graph is a graphical representation of a model which shows each variable as a circle and each factor or constraint as a square. If a variable participates in the factor or the constraint, then an edge is shown between the corresponding circle and square. Factor graphs are more than just a picture of the model; they are intimately related to the message passing algorithms used for inference in Infer.NET.

// Show the factor graph of the model  
engine.ShowFactorGraph = true;

The default setting for this bool property is false.


If not null, all factor graphs generated by calls to Infer will be saved to the given folder (which will be created if it doesn’t already exist). The graph is saved in DGML format, which can be viewed and manipulated in Visual Studio. The file name is the model name, with extension “.dgml”. If the folder name is an empty string (as opposed to null), the graphs will be saved to the current folder.

// Save all factor graphs to the 'graphs' sub-folder  
engine.SaveFactorGraphToFolder = "graphs";

The default setting for this string property is null.


If this flag is set to true, the Model Specification Language (MSL) version of your model will be written to the Console

// Show the model in the Model Specification Language  
engine.ShowMsl = true;

The default setting for this bool property is false.


If this flag is set to true, progress information is written to the console, updating at each iteration.

// Print out progress information  
engine.ShowProgress = true;

The default setting for this bool property is true.


If this flag is set to true, timing information is written to the console at the conclusion of the inference, showing the time taken for compilation (if compilation is done) and for inference.

// Print out timing information  
engine.ShowTimings = true;

The default setting for this bool property is false.


If this flag is set to true, any warnings encountered during inference will be printed to the console. The default setting for this bool property is true, so that you are aware of any problems encountered. To suppress warnings, set the property to false.

// Do not print out warnings  
engine.ShowWarnings = false;


This is a global setting that provides the implementation of ShowFactorGraph, ShowSchedule, and BrowserMode for the platform. Defaults to DefaultVisualizer.

// Custom visualization for the Windows platform
InferenceEngine.Visualizer = new WindowsVisualizer();