Commit dffdd545 authored by Christoph Groth's avatar Christoph Groth
Browse files

discretizer: docstring clarifications and extra examples

parent e1c6cbf6
......@@ -39,38 +39,35 @@ del default_subs['I']
del default_subs['pi']
################ Various helpers to handle sympy
################ Helpers to handle sympy
def lambdify(expr, subs=None):
"""Return a callable object for computing a continuum Hamiltonian.
def lambdify(hamiltonian, subs=None):
"""Return a callable object for computing continuum Hamiltonian.
.. warning::
This function uses ``eval`` (because it calls ``sympy.sympify``), and
thus should not be used on unsanitized input.
Parameters
----------
hamiltonian : sympy.Expr or sympy.Matrix, or string
Symbolic representation of a continous Hamiltonian. When providing
a sympy expression, it is recommended to use ``momentum_operators``
defined in `~kwant.continuum` in order to provide
proper commutation properties. If a string is provided it will be
converted to a sympy expression using `kwant.continuum.sympify`.
subs: dict, defaults to empty
A namespace of substitutions to be performed on the input
``hamiltonian``. It can be used to simplify input of matrices or
alternate input before proceeding further. Please see examples below.
expr : str or SymPy expression
Expression to be converted into a callable object
subs : dict or ``None`` (default)
Namespace of substitutions to be performed on `expr`.
Example:
--------
>>> f = kwant.continuum.lambdify('a + b', subs={'b': 'b + c'})
>>> f = lambdify('a + b', subs={'b': 'b + c'})
>>> f(1, 3, 5)
9
>>> subs = {'s_z': [[1, 0], [0, -1]]}
>>> f = kwant.continuum.lambdify('k_z**2 * s_z', subs=subs)
>>> f(.25)
array([[ 0.0625, 0. ],
[ 0. , -0.0625]])
>>> subs = {'sigma_plus': [[0, 2], [0, 0]]}
>>> f = lambdify('k_x**2 * sigma_plus', subs)
>>> f(0.25)
array([[ 0. , 0.125],
[ 0. , 0. ]])
"""
expr = sympify(hamiltonian, subs)
expr = sympify(expr, subs)
args = [s.name for s in expr.atoms(sympy.Symbol)]
args += [str(f.func) for f in expr.atoms(AppliedUndef, sympy.Function)]
......@@ -97,20 +94,27 @@ def sympify(expr, subs=None):
In addition, Python list literals are interpreted as SymPy matrices.
.. warning::
Note that this function uses ``eval`` (because it calls
``sympy.sympify``), and thus shouldn't be used on unsanitized input.
This function uses ``eval`` (because it calls ``sympy.sympify``), and
thus should not be used on unsanitized input.
If `expr` is already a SymPy expression or a SymPy matrix, both the keys
and the values of `subs` are sympified (with the above special rules in
force) and used to to perform substitution using the ``.subs`` method of
`expr`.
If `expr` is a SymPy expression or a SymPy matrix, both the keys and values
of `subs` are sympified (without the above special rules) and used to to
perform substitution using the ``.subs`` method of `expr`. The input
expression is not altered otherwise.
.. note::
Any (part of) argument to this function that gets sympified (for
example the values of `subs`) may be already a SymPy object. In this
case it is left unchanged. In particular, the commutativity of its
terms is not altered. This possibly confusing effect is demonstrated
in the last example below.
Parameters
----------
expr : str or SymPy expression
The expression to be converted to a SymPy object.
Expression to be converted to a SymPy object.
subs : dict or ``None`` (default)
The namespace of substitutions to be performed on the input `expr`.
Namespace of substitutions to be performed on the input `expr`.
If `expr` is a string, the keys must be strings as well. Otherwise
they may be any sympifyable object. The values must be sympifyable
objects.
......@@ -121,22 +125,23 @@ def sympify(expr, subs=None):
Examples
--------
>>> from kwant.continuum import sympify
>>> sympify('k_x * A(x) * k_x + V(x)')
k_x*A(x)*k_x + V(x) # as valid sympy object
or
>>> from kwant.continuum import sympify
>>> sympify('k_x**2 + V', subs={'V': 'V_0 + V(x)'})
k_x**2 + V(x) + V_0
>>> from kwant.continuum import sympify
>>> sympify('k_x**2 * sigma_plus',
... subs={'sigma_plus': [[0, 2], [0, 0]]})
>>> subs = {'sigma_plus': [[0, 2], [0, 0]]}
>>> sympify('k_x**2 * sigma_plus', subs)
Matrix([
[0, 2*k_x**2],
[0, 0]])
>>> sympify('k_x * A(c) * k_x', subs={'c': 'x'})
k_x*A(x)*k_x
>>> sympify('k_x * A(c) * k_x', subs={'c': sympy.Symbol('x')})
A(x)*k_x**2
"""
stored_value = None
sympified_types = (sympy.Expr, sympy.matrices.MatrixBase)
......
......@@ -88,34 +88,36 @@ def discretize(hamiltonian, coords=None, *, grid_spacing=1,
`~kwant.continuum.discretize_symbolic` and feeding its result into
`~kwant.continuum.build_discretized`.
.. warning::
This function uses ``eval`` (because it calls ``sympy.sympify``), and
thus should not be used on unsanitized input.
Parameters
----------
hamiltonian : sympy.Expr or sympy.Matrix, or string
Symbolic representation of a continous Hamiltonian. When providing
a sympy expression, it is recommended to use ``momentum_operators``
defined in `~kwant.continuum` in order to provide
proper commutation properties. If a string is provided it will be
converted to a sympy expression using `kwant.continuum.sympify`.
hamiltonian : string, or sympy.Expr, or sympy.Matrix
Symbolic representation of a continous Hamiltonian. It is
converted to a SymPy expression using `kwant.continuum.sympify`.
coords : sequence of strings, or ``None`` (default)
The coordinates for which momentum operators will be treated as
differential operators. May contain only "x", "y" and "z" and must be
sorted. If not provided, `coords` will be obtained from the input
Hamiltonian by reading the present coordinates and momentum operators.
grid_spacing : int or float, default: 1
Grid spacing for the template Builder.
subs : dict, defaults to empty
A namespace of substitutions to be performed on the input
``hamiltonian``. Values can be either strings or ``sympy`` objects.
It can be used to simplify input of matrices or alternate input before
proceeding further. For example:
Spacing of the (quadratic or cubic) discretization grid.
subs : dict or ``None`` (default)
A namespace of substitutions to be performed on `hamiltonian`. See
`kwant.continuum.sympify` for details. May be used to simplify input of
matrices or alternate input before proceeding further. For example:
``subs={'k': 'k_x + I * k_y'}`` or
``subs={'s_z': [[1, 0], [0, -1]]}``.
``subs={'sigma_plus': [[0, 2], [0, 0]]}``.
Returns
-------
template: `~kwant.builder.Builder`
model: `~kwant.builder.Builder`
The translationally symmetric builder that corresponds to the provided
Hamiltonian.
Hamiltonian. It may be passed directly into the method
`~kwant.builder.Builder.fill` of a builder to construct a system of a
desired shape.
"""
tb, coords = discretize_symbolic(hamiltonian, coords, subs=subs)
......@@ -128,30 +130,30 @@ def discretize_symbolic(hamiltonian, coords=None, *, subs=None):
The two objects returned by this function may be used directly as the first
two arguments for `~kwant.continuum.build_discretized`.
.. warning::
This function uses ``eval`` (because it calls ``sympy.sympify``), and
thus should not be used on unsanitized input.
Parameters
----------
hamiltonian : sympy.Expr or sympy.Matrix, or string
Symbolic representation of a continuous Hamiltonian. When providing
a sympy expression, it is recommended to use ``momentum_operators``
defined in `~kwant.continuum` in order to provide
proper commutation properties. If a string is provided it will be
hamiltonian : string, or sympy.Expr, or sympy.Matrix
Symbolic representation of a continous Hamiltonian. It is
converted to a sympy expression using `kwant.continuum.sympify`.
coords : sequence of strings, or ``None`` (default)
The coordinates for which momentum operators will be treated as
differential operators. May contain only "x", "y" and "z" and must be
sorted. If not provided, `coords` will be obtained from the input
Hamiltonian by reading the present coordinates and momentum operators.
subs: dict, defaults to empty
A namespace of substitutions to be performed on the input
``hamiltonian``. Values can be either strings or ``sympy`` objects.
It can be used to simplify input of matrices or alternate input before
proceeding further. For example:
subs : dict, defaults to empty
A namespace of substitutions to be performed on `hamiltonian`. See
`kwant.continuum.sympify` for details. May be used to simplify input of
matrices or alternate input before proceeding further. For example:
``subs={'k': 'k_x + I * k_y'}`` or
``subs={'s_z': [[1, 0], [0, -1]]}``.
``subs={'sigma_plus': [[0, 2], [0, 0]]}``.
Returns
-------
tb_hamiltonian: dict
tb_hamiltonian : dict
Keys are tuples of integers; the offsets of the hoppings ((0, 0, 0) for
the onsite). Values are symbolic expressions for the hoppings/onsite.
coords : list of strings
......@@ -213,39 +215,44 @@ def discretize_symbolic(hamiltonian, coords=None, *, subs=None):
return tb, coords
def build_discretized(tb_hamiltonian, coords, *,
grid_spacing=1, subs=None):
"""Create a template Builder from a symbolic tight-binding Hamiltonian.
def build_discretized(tb_hamiltonian, coords, *, grid_spacing=1, subs=None):
"""Create a template builder from a symbolic tight-binding Hamiltonian.
This return values of `~kwant.continuum.discretize_symbolic` may be used
The return values of `~kwant.continuum.discretize_symbolic` may be used
directly for the first two arguments of this function.
.. warning::
This function uses ``eval`` (because it calls ``sympy.sympify``), and
thus should not be used on unsanitized input.
Parameters
----------
tb_hamiltonian : dict
Keys are tuples of integers: the offsets of the hoppings
((0, 0, 0) for the onsite). Values are symbolic expressions
for the hoppings/onsite or expressions that can by sympified using
Keys must be the offsets of the hoppings, represented by tuples of
integers ((0, 0, 0) for onsite). Values must be symbolic expressions
for the hoppings/onsite or expressions that can by sympified with
`kwant.continuum.sympify`.
coords : sequence of strings
The coordinates for which momentum operators will be treated as
differential operators. May contain only "x", "y" and "z" and must be
sorted.
grid_spacing : int or float, default: 1
Grid spacing for the template Builder.
subs: dict, defaults to empty
A namespace of substitutions to be performed on the values of input
`tb_hamiltonian`. Values can be either strings or ``sympy`` objects.
It can be used to simplify input of matrices or alternate input before
proceeding further. For example:
``subs={'k': 'k_x + I * k_y'}`` or
``subs={'s_z': [[1, 0], [0, -1]]}``.
Spacing of the (quadratic or cubic) discretization grid.
subs : dict, defaults to empty
A namespace of substitutions to be performed on the values of
`tb_hamiltonian`. See `kwant.continuum.sympify` for details. May be
used to simplify input of matrices or alternate input before proceeding
further. For example: ``subs={'k': 'k_x + I * k_y'}`` or
``subs={'sigma_plus': [[0, 2], [0, 0]]}``.
Returns
-------
template: `~kwant.builder.Builder`
model : `~kwant.builder.Builder`
The translationally symmetric builder that corresponds to the provided
Hamiltonian.
Hamiltonian. It may be passed directly into the method
`~kwant.builder.Builder.fill` of a builder to construct a system of a
desired shape.
"""
if len(coords) == 0:
raise ValueError('Discrete coordinates cannot be empty.')
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment