Commit 4f692156 authored by Martin Reinecke's avatar Martin Reinecke
Browse files

Merge branch 'mr_docs' into 'NIFTy_5'

more docs

See merge request ift/nifty-dev!179
parents 0aa213dd d2eb468e
...@@ -187,6 +187,18 @@ class Linearization(object): ...@@ -187,6 +187,18 @@ class Linearization(object):
return self.__mul__(other) return self.__mul__(other)
def outer(self, other): def outer(self, other):
"""Computes the outer product of this Linearization with a Field or
another Linearization
Parameters
----------
other : Field or MultiField or Linearization
Returns
-------
Linearization
the outer product of self and other
"""
from .operators.outer_product_operator import OuterProduct from .operators.outer_product_operator import OuterProduct
if isinstance(other, Linearization): if isinstance(other, Linearization):
return self.new( return self.new(
...@@ -200,6 +212,18 @@ class Linearization(object): ...@@ -200,6 +212,18 @@ class Linearization(object):
OuterProduct(self._jac(self._val), other.domain)) OuterProduct(self._jac(self._val), other.domain))
def vdot(self, other): def vdot(self, other):
"""Computes the inner product of this Linearization with a Field or
another Linearization
Parameters
----------
other : Field or MultiField or Linearization
Returns
-------
Linearization
the inner product of self and other
"""
from .operators.simple_linear_operators import VdotOperator from .operators.simple_linear_operators import VdotOperator
if isinstance(other, (Field, MultiField)): if isinstance(other, (Field, MultiField)):
return self.new( return self.new(
...@@ -211,6 +235,19 @@ class Linearization(object): ...@@ -211,6 +235,19 @@ class Linearization(object):
VdotOperator(other._val)(self._jac)) VdotOperator(other._val)(self._jac))
def sum(self, spaces=None): def sum(self, spaces=None):
"""Computes the (partial) sum over self
Parameters
----------
spaces : None, int or list of int
- if None, sum over the entire domain
- else sum over the specified subspaces
Returns
-------
Linearization
the (partial) sum
"""
from .operators.contraction_operator import ContractionOperator from .operators.contraction_operator import ContractionOperator
if spaces is None: if spaces is None:
return self.new( return self.new(
...@@ -222,6 +259,19 @@ class Linearization(object): ...@@ -222,6 +259,19 @@ class Linearization(object):
ContractionOperator(self._jac.target, spaces)(self._jac)) ContractionOperator(self._jac.target, spaces)(self._jac))
def integrate(self, spaces=None): def integrate(self, spaces=None):
"""Computes the (partial) integral over self
Parameters
----------
spaces : None, int or list of int
- if None, integrate over the entire domain
- else integrate over the specified subspaces
Returns
-------
Linearization
the (partial) integral
"""
from .operators.contraction_operator import ContractionOperator from .operators.contraction_operator import ContractionOperator
if spaces is None: if spaces is None:
return self.new( return self.new(
...@@ -309,18 +359,72 @@ class Linearization(object): ...@@ -309,18 +359,72 @@ class Linearization(object):
@staticmethod @staticmethod
def make_var(field, want_metric=False): def make_var(field, want_metric=False):
"""Converts a Field to a Linearization, with a unity Jacobian
Parameters
----------
field : Field or Multifield
the field to be converted
want_metric : bool
If True, the metric will be computed for other Linearizations
derived from this one. Default: False.
Returns
-------
Linearization
the requested Linearization
"""
from .operators.scaling_operator import ScalingOperator from .operators.scaling_operator import ScalingOperator
return Linearization(field, ScalingOperator(1., field.domain), return Linearization(field, ScalingOperator(1., field.domain),
want_metric=want_metric) want_metric=want_metric)
@staticmethod @staticmethod
def make_const(field, want_metric=False): def make_const(field, want_metric=False):
"""Converts a Field to a Linearization, with a zero Jacobian
Parameters
----------
field : Field or Multifield
the field to be converted
want_metric : bool
If True, the metric will be computed for other Linearizations
derived from this one. Default: False.
Returns
-------
Linearization
the requested Linearization
Notes
-----
The Jacobian is square and contains only zeroes.
"""
from .operators.simple_linear_operators import NullOperator from .operators.simple_linear_operators import NullOperator
return Linearization(field, NullOperator(field.domain, field.domain), return Linearization(field, NullOperator(field.domain, field.domain),
want_metric=want_metric) want_metric=want_metric)
@staticmethod @staticmethod
def make_const_empty_input(field, want_metric=False): def make_const_empty_input(field, want_metric=False):
"""Converts a Field to a Linearization, with a zero Jacobian
Parameters
----------
field : Field or Multifield
the field to be converted
want_metric : bool
If True, the metric will be computed for other Linearizations
derived from this one. Default: False.
Returns
-------
Linearization
the requested Linearization
Notes
-----
The Jacobian has an empty input domain, i.e. its matrix representation
has 0 columns.
"""
from .operators.simple_linear_operators import NullOperator from .operators.simple_linear_operators import NullOperator
from .multi_domain import MultiDomain from .multi_domain import MultiDomain
return Linearization( return Linearization(
...@@ -329,6 +433,29 @@ class Linearization(object): ...@@ -329,6 +433,29 @@ class Linearization(object):
@staticmethod @staticmethod
def make_partial_var(field, constants, want_metric=False): def make_partial_var(field, constants, want_metric=False):
"""Converts a MultiField to a Linearization, with a Jacobian that is
unity for some MultiField components and a zero matrix for others.
Parameters
----------
field : Multifield
the field to be converted
constants : list of string
the MultiField components for which the Jacobian should be
a zero matrix.
want_metric : bool
If True, the metric will be computed for other Linearizations
derived from this one. Default: False.
Returns
-------
Linearization
the requested Linearization
Notes
-----
The Jacobian is square.
"""
from .operators.scaling_operator import ScalingOperator from .operators.scaling_operator import ScalingOperator
from .operators.block_diagonal_operator import BlockDiagonalOperator from .operators.block_diagonal_operator import BlockDiagonalOperator
if len(constants) == 0: if len(constants) == 0:
......
...@@ -52,7 +52,8 @@ def PS_field(pspace, func): ...@@ -52,7 +52,8 @@ def PS_field(pspace, func):
Returns Returns
------- -------
Field : a field defined on (pspace,) containing the computed function values Field
A field defined on (pspace,) containing the computed function values
""" """
if not isinstance(pspace, PowerSpace): if not isinstance(pspace, PowerSpace):
raise TypeError raise TypeError
...@@ -209,6 +210,23 @@ def create_power_operator(domain, power_spectrum, space=None): ...@@ -209,6 +210,23 @@ def create_power_operator(domain, power_spectrum, space=None):
def create_harmonic_smoothing_operator(domain, space, sigma): def create_harmonic_smoothing_operator(domain, space, sigma):
"""Creates an operator which smoothes a subspace of a harmonic domain.
Parameters
----------
domain: DomainTuple
The total domain and target of the operator
space : int
the index of the subspace on which the operator acts.
This must be a harmonic space
sigma : float
The sigma of the Gaussian smoothing kernel
Returns
-------
DiagonalOperator
The requested smoothing operator
"""
kfunc = domain[space].get_fft_smoothing_kernel_function(sigma) kfunc = domain[space].get_fft_smoothing_kernel_function(sigma)
return DiagonalOperator(kfunc(domain[space].get_k_length_array()), domain, return DiagonalOperator(kfunc(domain[space].get_k_length_array()), domain,
space) space)
...@@ -226,7 +244,8 @@ def full(domain, val): ...@@ -226,7 +244,8 @@ def full(domain, val):
Returns Returns
------- -------
Field / MultiField : the newly created uniform field Field or MultiField
The newly created uniform field
""" """
if isinstance(domain, (dict, MultiDomain)): if isinstance(domain, (dict, MultiDomain)):
return MultiField.full(domain, val) return MultiField.full(domain, val)
...@@ -249,7 +268,8 @@ def from_random(random_type, domain, dtype=np.float64, **kwargs): ...@@ -249,7 +268,8 @@ def from_random(random_type, domain, dtype=np.float64, **kwargs):
Returns Returns
------- -------
Field / MultiField : the newly created random field Field or MultiField
The newly created random field
""" """
if isinstance(domain, (dict, MultiDomain)): if isinstance(domain, (dict, MultiDomain)):
return MultiField.from_random(random_type, domain, dtype, **kwargs) return MultiField.from_random(random_type, domain, dtype, **kwargs)
...@@ -274,7 +294,8 @@ def from_global_data(domain, arr, sum_up=False): ...@@ -274,7 +294,8 @@ def from_global_data(domain, arr, sum_up=False):
Returns Returns
------- -------
Field / MultiField : the newly created random field Field or MultiField
The newly created random field
""" """
if isinstance(domain, (dict, MultiDomain)): if isinstance(domain, (dict, MultiDomain)):
return MultiField.from_global_data(domain, arr, sum_up) return MultiField.from_global_data(domain, arr, sum_up)
...@@ -294,7 +315,8 @@ def from_local_data(domain, arr): ...@@ -294,7 +315,8 @@ def from_local_data(domain, arr):
Returns Returns
------- -------
Field / MultiField : the newly created field Field or MultiField
The newly created field
""" """
if isinstance(domain, (dict, MultiDomain)): if isinstance(domain, (dict, MultiDomain)):
return MultiField.from_local_data(domain, arr) return MultiField.from_local_data(domain, arr)
...@@ -311,7 +333,8 @@ def makeDomain(domain): ...@@ -311,7 +333,8 @@ def makeDomain(domain):
Returns Returns
------- -------
DomainTuple / MultiDomain : the newly created domain object DomainTuple or MultiDomain
The newly created domain object
""" """
if isinstance(domain, (MultiDomain, dict)): if isinstance(domain, (MultiDomain, dict)):
return MultiDomain.make(domain) return MultiDomain.make(domain)
...@@ -319,6 +342,21 @@ def makeDomain(domain): ...@@ -319,6 +342,21 @@ def makeDomain(domain):
def makeOp(input): def makeOp(input):
"""Converts a Field or MultiField to a diagonal operator.
Parameters
----------
input : None, Field or MultiField
- if None, None is returned.
- if Field, a DiagonalOperator with the coefficients given by this
Field is returned.
- if MultiField, a BlockDiagonalOperator with entries given by this
MultiField is returned.
Notes
-----
No volume factors are applied.
"""
if input is None: if input is None:
return None return None
if isinstance(input, Field): if isinstance(input, Field):
...@@ -330,6 +368,14 @@ def makeOp(input): ...@@ -330,6 +368,14 @@ def makeOp(input):
def domain_union(domains): def domain_union(domains):
"""Computes the union of multiple DomainTuples/MultiDomains.
Parameters
----------
domains : list of DomainTuple or MultiDomain
- if DomainTuple, all entries must be equal
- if MultiDomain, there must not be any conflicting components
"""
if isinstance(domains[0], DomainTuple): if isinstance(domains[0], DomainTuple):
if any(dom != domains[0] for dom in domains[1:]): if any(dom != domains[0] for dom in domains[1:]):
raise ValueError("domain mismatch") raise ValueError("domain mismatch")
......
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