# Python API Reference¶

## Chi2¶

mitsuba.python.chi2.BSDFAdapter(bsdf_type, extra, wi=[0, 0, 1], ctx=None)

Adapter to test BSDF sampling using the Chi^2 test.

Parameter bsdf_type (string):

Name of the BSDF plugin to instantiate.

Parameter extra (string):

Additional XML used to specify the BSDF’s parameters.

Parameter wi (array(3,)):

Incoming direction, in local coordinates.

class mitsuba.python.chi2.ChiSquareTest(domain, sample_func, pdf_func, sample_dim=2, sample_count=1000000, res=101, ires=4)

Implements Pearson’s chi-square test for goodness of fit of a distribution to a known reference distribution.

The implementation here specifically compares a Monte Carlo sampling strategy on a 2D (or lower dimensional) space against a reference distribution obtained by numerically integrating a probability density function over grid in the distribution’s parameter domain.

Parameter domain (object):

An implementation of the domain interface (SphericalDomain, etc.), which transforms between the parameter and target domain of the distribution

Parameter sample_func (function):

An importance sampling function which maps an array of uniform variates of size [sample_dim, sample_count] to an array of sample_count samples on the target domain.

Parameter pdf_func (function):

Function that is expected to specify the probability density of the samples produced by sample_func. The test will try to collect sufficient statistical evidence to reject this hypothesis.

Parameter sample_dim (int):

Number of random dimensions consumed by sample_func per sample. The default value is 2.

Parameter sample_count (int):

Total number of samples to be generated. The test will have more evidence as this number tends to infinity. The default value is 1000000.

Parameter res (int):

Vertical resolution of the generated histograms. The horizontal resolution will be calculated as res * domain.aspect(). The default value of 101 is intentionally an odd number to prevent issues with floating point precision at sharp boundaries that may separate the domain into two parts (e.g. top hemisphere of a sphere parameterization).

Parameter ires (int):

Number of horizontal/vertical subintervals used to numerically integrate the probability density over each histogram cell (using the trapezoid rule). The default value is 4.

Notes:

The following attributes are part of the public API:

messages: string

The implementation may generate a number of messages while running the test, which can be retrieved via this attribute.

histogram: array

The histogram array is populated by the tabulate_histogram() method and stored in this attribute.

pdf: array

The probability density function array is populated by the tabulate_pdf() method and stored in this attribute.

p_value: float

The p-value of the test is computed in the run() method and stored in this attribute.

tabulate_histogram()

Invoke the provided sampling strategy many times and generate a histogram in the parameter domain. If sample_func returns a tuple (positions, weights) instead of just positions, the samples are considered to be weighted.

tabulate_pdf()

Numerically integrate the provided probability density function over each cell to generate an array resembling the histogram computed by tabulate_histogram(). The function uses the trapezoid rule over intervals discretized into self.ires separate function evaluations.

run(significance_level=0.01, test_count=1, quiet=False)

Run the Chi^2 test

Parameter significance_level (float):

Denotes the desired significance level (e.g. 0.01 for a test at the 1% significance level)

Parameter test_count (int):

Specifies the total number of statistical tests run by the user. This value will be used to adjust the provided significance level so that the combination of the entire set of tests has the provided significance level.

Returns → bool:

True upon success, False if the null hypothesis was rejected.

class mitsuba.python.chi2.LineDomain(bounds=[- 1.0, 1.0])

The identity map on the line.

mitsuba.python.chi2.MicrofacetAdapter(md_type, alpha, sample_visible=False)

Adapter for testing microfacet distribution sampling techniques (separately from BSDF models, which are also tested)

mitsuba.python.chi2.PhaseFunctionAdapter(phase_type, extra, wi=[0, 0, 1])

Adapter to test phase function sampling using the Chi^2 test.

Parameter phase_type (string):

Name of the phase function plugin to instantiate.

Parameter extra (string):

Additional XML used to specify the phase function’s parameters.

Parameter wi (array(3,)):

Incoming direction, in local coordinates.

class mitsuba.python.chi2.PlanarDomain(bounds=None)

The identity map on the plane

mitsuba.python.chi2.SpectrumAdapter(value)

Adapter which permits testing 1D spectral power distributions using the Chi^2 test.

class mitsuba.python.chi2.SphericalDomain

Maps between the unit sphere and a [cos(theta), phi] parameterization.

## Autodiff¶

class mitsuba.python.autodiff.Adam(params, lr, beta_1=0.9, beta_2=0.999, epsilon=1e-08)

Base class: mitsuba.python.autodiff.Optimizer

Implements the Adam optimizer presented in the paper Adam: A Method for Stochastic Optimization by Kingman and Ba, ICLR 2015.

__init__(params, lr, beta_1=0.9, beta_2=0.999, epsilon=1e-08)
Parameter lr:

learning rate

Parameter beta_1:

controls the exponential averaging of first order gradient moments

Parameter beta_2:

controls the exponential averaging of second order gradient moments

step()

class mitsuba.python.autodiff.Optimizer(params, lr)

__init__(params, lr)
Parameter params:

dictionary (name: variable) of differentiable parameters to be optimized.

Parameter lr:

learning rate

set_learning_rate(lr)

Set the learning rate.

disable_gradients()

Temporarily disable the generation of gradients.

class mitsuba.python.autodiff.SGD(params, lr, momentum=0)

Base class: mitsuba.python.autodiff.Optimizer

Implements basic stochastic gradient descent with a fixed learning rate and, optionally, momentum [SMDH13] (0.9 is a typical parameter value for the momentum parameter).

The momentum-based SGD uses the update equation

$v_{i+1} = \mu \cdot v_i + g_{i+1}$
$p_{i+1} = p_i + \varepsilon \cdot v_{i+1},$

where $$v$$ is the velocity, $$p$$ are the positions, $$\varepsilon$$ is the learning rate, and $$\mu$$ is the momentum parameter.

__init__(params, lr, momentum=0)
Parameter lr:

learning rate

Parameter momentum:

momentum factor

step()

mitsuba.python.autodiff._render_helper(scene, spp=None, sensor_index=0)

Internally used function: render the specified Mitsuba scene and return a floating point array containing RGB values and AOVs, if applicable

mitsuba.python.autodiff.render(scene, spp: Union[None, int, Tuple[int, int]] = None, unbiased=False, optimizer: mitsuba.python.autodiff.Optimizer = None, sensor_index=0)

Perform a differentiable of the scene scene, returning a floating point array containing RGB values and AOVs, if applicable.

Parameter spp (None, int, or a 2-tuple (int, int)):

Specifies the number of samples per pixel to be used for rendering, overriding the value that is specified in the scene. If spp=None, the original value takes precedence. If spp is a 2-tuple (spp_primal: int, spp_deriv: int), the first element specifies the number of samples for the primal pass, and the second specifies the number of samples for the derivative pass. See the explanation of the unbiased parameter for further detail on what these mean.

Memory usage is roughly proportional to the spp, value, hence this parameter should be reduced if you encounter out-of-memory errors.

Parameter unbiased (bool):

One potential issue when naively differentiating a rendering algorithm is that the same set of Monte Carlo sample is used to generate both the primal output (i.e. the image) along with derivative output. When the rendering algorithm and objective are jointly differentiated, we end up with expectations of products that do not satisfy the equality $$\mathbb{E}[X Y]=\mathbb{E}[X]\, \mathbb{E}[Y]$$ due to correlations between $$X$$ and $$Y$$ that result from this sample re-use.

When unbiased=True, the render() function will generate an unbiased estimate that de-correlates primal and derivative components, which boils down to rendering the image twice and naturally comes at some cost in performance $$(\sim 1.6 imes\!)$$. Often, biased gradients are good enough, in which case unbiased=False should be specified instead.

The number of samples per pixel per pass can be specified separately for both passes by passing a tuple to the spp parameter.

Note that unbiased mode is only relevant for reverse-mode differentiation. It is not needed when visualizing parameter gradients in image space using forward-mode differentiation.

Parameter optimizer (mitsuba.python.autodiff.Optimizer):

The optimizer referencing relevant scene parameters must be specified when unbiased=True. Otherwise, there is no need to provide this parameter.

Parameter sensor_index (int):

When the scene contains more than one sensor/camera, this parameter can be specified to select the desired sensor.

mitsuba.python.autodiff.render_torch(scene, params=None, **kwargs)

mitsuba.python.autodiff.write_bitmap(filename, data, resolution, write_async=True)

Write the linearized RGB image in data to a PNG/EXR/.. file with resolution resolution.

## Other¶

class mitsuba.python.util.ParameterMap(properties, hierarchy)

Dictionary-like object that references various parameters used in a Mitsuba scene graph. Parameters can be read and written using standard syntax (parameter_map[key]). The class exposes several non-standard functions, specifically torch(), update(), and keep().

__init__(properties, hierarchy)

Private constructor (use mitsuba.python.util.traverse() instead)

torch() → dict

Converts all Enoki arrays into PyTorch arrays and return them as a dictionary. This is mainly useful when using PyTorch to optimize a Mitsuba scene.

set_dirty(key: str)

Marks a specific parameter and its parent objects as dirty. A subsequent call to update() will refresh their internal state. This function is automatically called when overwriting a parameter using __setitem__().

update() → None

This function should be called at the end of a sequence of writes to the dictionary. It automatically notifies all modified Mitsuba objects and their parent objects that they should refresh their internal state. For instance, the scene may rebuild the kd-tree when a shape was modified, etc.

keep(keys: list) → None

Reduce the size of the dictionary by only keeping elements, whose keys are part of the provided list ‘keys’.

mitsuba.python.util.is_differentiable(p)

mitsuba.python.util.traverse(node: mitsuba.core.Object)mitsuba.python.util.ParameterMap

Traverse a node of Mitsuba’s scene graph and return a dictionary-like object that can be used to read and write associated scene parameters.

mitsuba.python.math.rlgamma(a, x)

Regularized lower incomplete gamma function based on CEPHES

class mitsuba.python.xml.Files

Enum for different files or dicts containing specific info

class mitsuba.python.xml.WriteXML(path, split_files=False)

File Writing API Populates a dictionary with scene data, then writes it to XML.

data_add(key, value, file=0)

Add an entry to a given subdict.

key: dict key value: entry file: the subdict to which to add the data

add_comment(comment, file=0)

Add a comment to the scene dict

comment: text of the comment file: the subdict to which to add the comment

add_include(file)

Add an include tag to the main file. This is used when splitting the XML scene file in multiple fragments.

file: the file to include

wf(ind, st, tabs=0)

Write a string to file index ind. Optionally indent the string by a number of tabs

ind: index of the file to write to st: text to write tabs: optional number of tabs to add

set_filename(name)

Open the files for output, using filenames based on the given base name. Create the necessary folders to create the file at the specified path.

name: path to the scene.xml file to write.

set_output_file(file)

Switch next output to the given file index

file: index of the file to start writing to

write_comment(comment, file=None)

Write an XML comment to file.

comment: The text of the comment to write file: Index of the file to write to

write_header(file, comment=None)

Write an XML header to a specified file. Optionally add a comment to describe the file.

file: The file to write to comment: Optional comment to add (e.g. “# Geometry file”)

open_element(name, attributes={}, file=None)

Open an XML tag (e.g. emitter, bsdf…)

name: Name of the tag (emitter, bsdf, shape…) attributes: Additional fileds to add to the opening tag (e.g. name, type…) file: File to write to

close_element(file=None)

Close the last tag we opened in a given file.

file: The file to write to

element(name, attributes={}, file=None)

Write a single-line XML element.

name: Name of the element (e.g. integer, string, rotate…) attributes: Additional fields to add to the element (e.g. name, value…) file: The file to write to

get_plugin_tag(plugin_type)

Get the corresponding tag of a given plugin (e.g. ‘bsdf’ for ‘diffuse’) If the given type (e.g. ‘transform’) is not a plugin, returns None.

plugin_type: Name of the type (e.g. ‘diffuse’, ‘ply’…)

current_tag()

Get the tag in which we are currently writing

configure_defaults(scene_dict)

Traverse the scene graph and look for properties in the defaults dict. For such properties, store their value in a default tag and replace the value by \$name in the prop.

scene_dict: The dictionary containing the scene info

preprocess_scene(scene_dict)
Preprocess the scene dictionary before writing it to file:

• Reorder the scene dict before writing it to file.

• Separate the dict into different category-specific subdicts.

• If not splitting files, merge them in the end.

scene_dict: The dictionary containing the scene data

format_spectrum(entry, entry_type)

Format rgb or spectrum tags to the proper XML output. The entry should contain the name and value of the spectrum entry. The type is passed separately, since it is popped from the dict in write_dict

entry: the dict containing the spectrum entry_type: either ‘spectrum’ or ‘rgb’

format_path(filepath, tag)

Given a filepath, either copy it in the scene folder (in the corresponding directory) or convert it to a relative path.

filepath: the path to the given file tag: the tag this path property belongs to in (shape, texture, spectrum)

write_dict(data)

Main XML writing routine. Given a dictionary, iterate over its entries and write them to file. Calls itself for nested dictionaries.

data: The dictionary to write to file.

process(scene_dict)

Preprocess then write the input dict to XML file format

scene_dict: The dictionary containing all the scene info.

transform_matrix(transform)

Converts a mitsuba Transform4f into a dict entry. This dict entry won’t have a ‘type’ because it’s handled in a specific case.

transform: the given transform matrix

decompose_transform(transform, export_scale=False)

Export a transform as a combination of rotation, scale and translation. This helps manually modifying the transform after export (for cameras for instance)

transform: The Transform4f transform matrix to decompose export_scale: Whether to add a scale property or not. (e.g. don’t do it for cameras to avoid clutter)

mitsuba.python.xml.copy2(src, dst, *, follow_symlinks=True)

Copy data and metadata. Return the file’s destination.

The destination may be a directory.

If follow_symlinks is false, symlinks won’t be followed. This resembles GNU’s “cp -P src dst”.

mitsuba.python.xml.dict_to_xml(scene_dict, filename, split_files=False)

mitsuba.python.test.util.fresolver_append_path(func)

Function decorator that adds the mitsuba project root to the FileResolver’s search path. This is useful in particular for tests that e.g. load scenes, and need to specify paths to resources.

The file resolver is restored to its previous state once the test’s execution has finished.

mitsuba.python.test.util.getframeinfo(frame, context=1)

Get information about a frame or traceback object.

A tuple of five things is returned: the filename, the line number of the current line, the function name, a list of lines of context from the source code, and the index of the current line within that list. The optional second argument specifies the number of lines of context to return, which are centered around the current line.

mitsuba.python.test.util.make_tmpfile(request, tmpdir_factory)

mitsuba.python.test.util.stack(context=1)

Return a list of records for the stack above the caller’s frame.

mitsuba.python.test.util.tmpfile(request, tmpdir_factory)

Fixture to create a temporary file

mitsuba.python.test.util.wraps`(wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated=('__dict__'))

Decorator factory to apply update_wrapper() to a wrapper function

Returns a decorator that invokes update_wrapper() with the decorated function as the wrapper argument and the arguments to wraps() as the remaining arguments. Default arguments are as for update_wrapper(). This is a convenience function to simplify applying partial() to update_wrapper().