TBTK
PropertyExtractors

See more details about the PropertyExtractors in the API

# A uniform interface for Solvers

A PropertyExtractor provides an interface to a Solver through which physical Properties can be extracted. Its purpose is to insulate the application developer from method-specific details. By wrapping a Solver in a PropertyExtractor, it acquires an interface that is largely uniform across different Solvers. This makes it possible to change Solver without having to modify the code used to extract Properties.

Each Solver comes with its own PropertyExtractor. The PropertyExtractors have the same name as the corresponding Solver but exists in the PropertyExtractor namespace rather than the Solver namespace. For example, Solver::Diagonalizer and PropertyExtractor::Diagonalizer. It is created as follows.

PropertyExtractor::Diagonalizer propertyExtractor(solver);

The PropertyExtractors corresponding to the other three production ready Solvers are:

Since not every Solver can be used to calculate every Property, the PropertyExtractors are only approximately uniform. For many standard Properties, the PropertyExtractors, therefore, fall back on printing an error message whenever a given Property cannot be calculated. This informs the application developer that another Solver may be required for the given task.

# Extracting Properties

The Properties that are extracted with the PropertyExtractors can be stored in different formats: None, Ranges, and Custom. This refers to how the Indices associated with the Properties are handled internally (more details can be found in the Properties chapter). Which format the Property is extracted in depends on the way the PropertyExtractor is called.

Properties without an Index structure have the format None and are extracted through calls with zero arguments.

propertyExtractor.calculateProperty();

Note that Property in calculateProperty() is a placeholder for the name of the actual Property to extract.

Properties with an Index structure can be extracted on the Ranges format by passing in a pattern-ranges pair.

propertyExtractor.calculateProperty(pattern, ranges);

Here pattern is an Index such as {3, IDX_X, IDX_SUM_ALL, IDX_Y}. It tells the PropertyExtractor to extract the Property for all Indices of the form {3, *, *, *}, summing over the third Subindex. Similarly, ranges is an Index such as {1, 10, 5, 2}. It tells the PropertyExtractor that the second, third, and fourth Subindices runs over 0 to 9, 0 to 5, and 0 to 1, respectively. The first Subindex is ignored but is usefully set to 1 to clarify that it takes on a single value.

Properties with an Index structure can also be extracted on the Custom format by passing in a list of patterns.

propertyExtractor.calculateProperty({
{0, _a_, IDX_SUM_ALL},
{_a_, 5, IDX_SUM_ALL}
});

This tells the PropertyExtractor to include all Indices of the form {0, *, *} and {*, 5, *}, summing over the third Subindex. The list of patterns can be arbitrary long. We note the extra pair of curly braces next to the parentheses. Without these, the call would have been interpreted as an attempt to extract the Property on the Ranges format.

# Energy-dependent Properties

Many Properties are energy-dependent. It is possible to set the range and resolution of the energy interval for which the PropertyExtractor calculates them.

propertyExtractor.setEnergyWindow(
lowerBound,
upperBound,
resolution
);

The resolution refers to the number of points between lowerBound and upperBound for which the Property is calculated.

# Examples

## DOS

The density of states (DOS) has no Indices associated with it and can be extracted in the None format.

Property::DOS dos = propertyExtractor.calculateDOS();

## Density

Consider a Model with the Index structure {x, y, z, spin}. The Density in the plane $$y = 10$$ can be calculated on the Ranges format using

Property::Density density = propertyExtractor.calculateDensity(
{IDX_X, 10, IDX_Y, IDX_SUM_ALL},
{sizeX, 1, sizeZ, 2}
);

Note that IDX_X and IDX_Y are not related to the Subindices x and y. Rather, they are labels indicating the first and second Subindex to loop over.

For a less regular set of Indices, we can use the Custom format instead. The Density in the plane $$z = 10$$, along the line $$(y,z)=(5,15)$$, and the spin-down Density on the site $$(x,y,z)=(0,0,0)$$ can be extracted using.

Property::Density density = propertyExtractor.calculateDensity({
{_a_, _a_, 10, IDX_SUM_ALL},
{_a_, 5, 15, IDX_SUM_ALL},
{ 0, 0, 0, 1}
});

## LDOS

Assuming the Index structure {x, y, z, spin}, the LDOS can be extracted in the $$z = 10$$ plane and on the Ranges format using

Property::LDOS ldos = propertyExtractor.calculateLDOS(
{ IDX_X, IDX_Y, 10, IDX_SUM_ALL},
{SIZE_X, SIZE_Y, SIZE_Z, 2}
);

The Custom format can be used to extract it in the plane $$z=10$$, along the line $$(y,z)=(5,15)$$, and for the down spin on site $$(x,y,z)=(0,0,0)$$.

Property::LDOS ldos = propertyExtractor.calculateLDOS({
{_a_, _a_, 10, IDX_SUM_ALL},
{_a_, 5, 15, IDX_SUM_ALL},
{ 0, 0, 0, 1}
});

## Magnetization

Assuming the Index structure {x, y, z, spin}, the Magnetization can be extracted in the $$z = 10$$ plane and on the Ranges format using

Property::Magnetization magnetization
= propertyExtractor.calculateMagnetization(
{ IDX_X, IDX_Y, 10, IDX_SPIN},
{SIZE_X, SIZE_Y, SIZE_Z, 2}
);

Note the IDX_SPIN flag, which is necessary to indicate which Subindex that corresponds to spin.

The Custom format can be used to extract it in the plane $$z=10$$, along the line $$(y,z)=(5,15)$$, and on the site $$(x,y,z)=(0,0,0)$$.

Property::Magnetization magnetization
= propertyExtractor.calculateMagnetization({
{_a_, _a_, 10, IDX_SPIN},
{_a_, 5, 15, IDX_SPIN},
{ 0, 0, 0, IDX_SPIN}
});

## SpinPolairzedLDOS

Assuming the Index structure {x, y, z, spin}, the SpinPolarizedLDOS can be extracted in the $$z = 10$$ plane and on the Ranges format using

Property::SpinPolarizedLDOS spinPolarizedLDOS
= propertyExtractor.calculateSpinPolarizedLDOS(
{ IDX_X, IDX_Y, 10, IDX_SPIN},
{SIZE_X, SIZE_Y, SIZE_Z, 2}
);

Note the IDX_SPIN flag, which is necessary to indicate which Subindex that corresponds to spin.

The Custom format can be used to extract it in the plane $$z=10$$, along the line $$(y,z)=(5,15)$$, and on the site $$(x,y,z)=(0,0,0)$$.

Property::SpinPolarizedLDOS spinPolarizedLDOS
= propertyExtractor.calculateSpinPolarizedLDOS({
{_a_, _a_, 10, IDX_SPIN},
{_a_, 5, 15, IDX_SPIN},
{ 0, 0, 0, IDX_SPIN}
});