Parameters and options

(We use parameter and option synonymously. See also the section on parameters in Simulations.

Standard simulations in TeNPy can be defined by just a set of options collected in a dictionary (possibly containing other parameter dictionaries). It can be convenient to represent these options in a [yaml] file, say parameters.yml, which might look like this:

simulation_class: GroundStateSearch

output_filename: results.h5

model_class:  SpinChain
model_params:
    L: 32
    bc_MPS: finite
    Jz: 1.

initial_state_params:
    method: lat_product_state
    product_state: [[up], [down]]

algorithm_class: TwoSiteDMRGEngine
algorithm_params:
    trunc_params:
        svd_min: 1.e-10
        chi_max: 100
    mixer: True

Note that the default values and even the allowed/used option names often depend on other parameters. For example, the model_class parameter above given to a Simulation selects a model class, and different model classes might have completely different parameters. This gives you freedom to easily define your own parameters when you implement a model, but it also makes it a little bit harder to keep track of allowed values.

In the TeNPy documentation, we use the Options sections of doc-strings to define parameters that are read out. Each documented parameter is attributed to one set of parameters, called “config”, and managed in a Config class at runtime. The above example represents the config for a Simulation, with the model_params representing the config given as options to the model for initialization. Sometimes, there is also a structure of one config including the parameters from another one: For example, the generic parameters for time evolution algorithms, TimeEvolutionAlgorithm are included into the TEBDEngine config, similarly to the sub-classing used.

During runtime, the Config class logs the first use of any parameter (with DEBUG log-level, if the default is used, and with INFO log-level, if it is non-default). Moreover, the default is saved into the parameter dictionary. Hence, it will contain the full set of all used parameters, default and non-default, at the end of a simulation, e.g., in the sim_params of the results returned by run().

Note

You can find a list of all the different configs in the Config Index, and a list of all parameters in Config-Options Index.

Note

If you add extra options to your configuration that TeNPy doesn’t read out by the end of the simulation, it will (usually) issue a warning. Getting such a warnings is an indicator for a typo in your configuration, or an option being in the wrong config dictionary.

Python snippets in yaml files

When defining the parameters in the yaml file, you might want to evaluate small formulas e.g., set a parameter to a certain fraction of $pi$, or expanding a long list [2**i for i in range(5, 10)] without explicitly writing all the entries. For those cases, it can be convenient to have small python snippets inside the yaml file, which we allow by loading the yaml files with tenpy.tools.params.load_yaml_with_py_eval().

It defines a !py_eval yaml tag, which should be followed by a string of python code to be evaluated with python’s eval() function. A good method to pass the python code is to use a literal string in yaml, as shown in the simple examples below.

a: !py_eval |
    2**np.arange(6, 10)
b: !py_eval |
    [10, 15] + list(range(20, 31, 2)) + [35, 40]
c: !py_eval "2*np.pi * 0.3"