Commit bdf8da70 authored by Anton Akhmerov's avatar Anton Akhmerov

rename substitute → substituted

This has a lower chance to give an impression that the substitution
happens in-place.

Closes gitlab issue #237
parent 7e4147d2
Pipeline #13085 passed with stages
in 26 minutes and 54 seconds
......@@ -53,16 +53,16 @@ filling a lower symmetry system with this model. Often, however, one wants
to use different parameter values in different parts of a system. In
previous versions of Kwant this was difficult to achieve.
Builders now have a method ``substitute`` that makes it easy to substitute
Builders now have a method ``substituted`` that makes it easy to substitute
different names for parameters. For example if a builder ``model``
has a parameter ``V``, and one wishes to have different values for ``V`` in
the scattering region and leads, one could do the following::
syst = kwant.Builder()
syst.fill(model.substitute(V='V_dot', ...))
syst.fill(model.substituted(V='V_dot', ...))
lead = kwant.Builder()
lead.fill(model.substitute(V='V_lead'), ...)
lead.fill(model.substituted(V='V_lead'), ...)
syst.attach_lead(lead)
fsyst = syst.finalized()
......
......@@ -1340,13 +1340,13 @@ class Builder:
self.update(other)
return self
def substitute(self, **subs):
def substituted(self, **subs):
"""Return a copy of this Builder with modified parameter names.
"""
# Construct the a copy of the system with new value functions.
if self.leads:
raise ValueError("For simplicity, 'subsitute' is limited "
"to builders without leads. Use 'substitute' "
raise ValueError("For simplicity, 'subsituted' is limited "
"to builders without leads. Use 'substituted' "
"before attaching leads to avoid this error.")
# Get value *functions* only
......
......@@ -1330,30 +1330,30 @@ def test_subs():
syst = make_system()
# substituting a paramter that doesn't exist produces a warning
warns(RuntimeWarning, syst.substitute, fakeparam='yes')
warns(RuntimeWarning, syst.substituted, fakeparam='yes')
# name clash in value functions
raises(ValueError, syst.substitute, b='a')
raises(ValueError, syst.substitute, b='c')
raises(ValueError, syst.substitute, a='site')
raises(ValueError, syst.substitute, c='sitea')
# cannot call 'substitute' on systems with attached leads, because
raises(ValueError, syst.substituted, b='a')
raises(ValueError, syst.substituted, b='c')
raises(ValueError, syst.substituted, a='site')
raises(ValueError, syst.substituted, c='sitea')
# cannot call 'substituted' on systems with attached leads, because
# it is not clear whether the substitutions should propagate
# into the leads too.
syst = make_system()
lead = make_system(kwant.TranslationalSymmetry((-1,)), n=1)
syst.attach_lead(lead)
raises(ValueError, syst.substitute, a='d')
raises(ValueError, syst.substituted, a='d')
# test basic substitutions
syst = make_system()
expected = hamiltonian(syst, a=1, b=2, c=3)
# 1 level of substitutions
sub_syst = syst.substitute(a='d', b='e')
sub_syst = syst.substituted(a='d', b='e')
assert np.allclose(hamiltonian(sub_syst, d=1, e=2, c=3), expected)
# 2 levels of substitution
sub_sub_syst = sub_syst.substitute(d='g', c='h')
sub_sub_syst = sub_syst.substituted(d='g', c='h')
assert np.allclose(hamiltonian(sub_sub_syst, g=1, e=2, h=3), expected)
# very confusing but technically valid. 'a' does not appear in 'hopping',
# so the signature of 'onsite' is valid.
sub_syst = syst.substitute(a='sitea')
sub_syst = syst.substituted(a='sitea')
assert np.allclose(hamiltonian(sub_syst, sitea=1, b=2, c=3), expected)
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