Operators

Available Operators

Operators are the core of ConvDO, the spatial derivate with corresponding code representation is listed as follows:

Operation	Operator initialization	Code of operation
\(\frac{\partial p }{ \partial x}\)	grad_x=ConvGrad(direction="x")	grad_x * p
\(\frac{\partial p }{ \partial y}\)	grad_x=ConvGrad(direction="y")	grad_y * p
\(\nabla p = (\frac{\partial p }{ \partial p},\frac{\partial p }{ \partial y})\)	nabla=ConvNabla()	nabla * p
\(\nabla \cdot \mathbf{u}=\frac{\partial u_x }{ \partial x}+\frac{\partial u_y }{ \partial y}\)	nabla=ConvNabla()	nabla @ u
\(\frac{\partial^2 p }{ \partial x^2}\)	grad2_x=ConvGrad2(direction="x")	grad2_x * p
\(\frac{\partial^2 p }{ \partial y^2}\)	grad2_x=ConvGrad2(direction="y")	grad2_y * p
\(\nabla^2 p = (\frac{\partial^2 p }{ \partial x^2},\frac{\partial^2 p }{ \partial y^2})\)	nabla2=ConvLaplacian()	nabla * p
\(\nabla \cdot (\nabla \mathbf{u}) = (\frac{\partial u_x }{ \partial x}+\frac{\partial u_x }{ \partial y},\frac{\partial u_y }{ \partial x}+\frac{\partial u_y }{ \partial y})\)	nabla2=ConvLaplacian()	nabla * u

Note: If you use ConvDO.operations.FieldOperations, the name of the operators is unchanged, e.g., the corresponding operator of grad_x is self.grad_x.

API Guide of Operators

ConvDO.conv_operators.ConvGrad

ConvGrad(
    order: int = 2,
    direction: str = "x",
    device="cpu",
    dtype=torch.float32,
)

Gradient operator \(\partial / \partial x\) or \(\partial / \partial y\) for a scalar.

Examples:

p=ScalarField(torch.rand(1,1,10,10))
grad_x = ConvGrad(order=2, direction="x", device="cpu", dtype=torch.float32)
grad_y = ConvGrad(order=2, direction="y", device="cpu", dtype=torch.float32)
grad_x*p # $\partial p / \partial x$ 
grad_y*p # $\partial p / \partial y$

Parameters:

Name	Type	Description	Default
order	int	The order of the central interpolation scheme (default is 2).	2
direction	str	The direction of the gradient operator, ("x" or "y", default is "x").	'x'
device	str	The device to use for computation (default is "cpu").	'cpu'
dtype	dtype	The data type to use for computation (default is torch.float32).	float32

Returns:

Name	Type	Description
ConvOperator	ConvOperator	The convolutional gradient operator.

Source code in ConvDO/conv_operators.py

def ConvGrad(order: int=2, direction: str="x", device="cpu", dtype=torch.float32):
    r"""
    Gradient operator $\partial / \partial x$ or $\partial / \partial y$ for a scalar.

    Examples:
        ```python
        p=ScalarField(torch.rand(1,1,10,10))
        grad_x = ConvGrad(order=2, direction="x", device="cpu", dtype=torch.float32)
        grad_y = ConvGrad(order=2, direction="y", device="cpu", dtype=torch.float32)
        grad_x*p # $\partial p / \partial x$ 
        grad_y*p # $\partial p / \partial y$
        ```

    Args:
        order (int): The order of the central interpolation scheme (default is 2).
        direction (str): The direction of the gradient operator, ("x" or "y", default is "x").
        device (str, optional): The device to use for computation (default is "cpu").
        dtype (torch.dtype, optional): The data type to use for computation (default is torch.float32).

    Returns:
        ConvOperator (ConvOperator): The convolutional gradient operator.

    """
    return ConvOperator(CENTRAL_INTERPOLATION_SCHEMES[order], direction=direction, derivative=1, device=device, dtype=dtype)

ConvDO.conv_operators.ConvNabla

ConvNabla(order: int, device='cpu', dtype=torch.float32)

\(\nabla=(\partial p / \partial x,\partial p / \partial y)\) operator. Can be used to compute the gradient of a scalar field or the divergence of a vector field.

Examples:

Gradient of a scalar field:
```python
p=ScalarField(torch.rand(1,1,10,10))
nabla = ConvNabla(order=2, device="cpu", dtype=torch.float32)
nabla*p # $\nabla p$
```

Divergence of a vector field:
```python
u=VectorValue(ScalarField(torch.rand(1,1,10,10)),ScalarField(torch.rand(1,1,10,10)))
nabla = ConvNabla(order=2, device="cpu", dtype=torch.float32)
nabla@u # $\nabla \cdot u$
```

Args: order (int): The order of the central interpolation scheme (default is 2). device (str, optional): The device to use for computation (default is "cpu"). dtype (torch.dtype, optional): The data type to use for computation (default is torch.float32).

Returns:

Name	Type	Description
ConvOperator	ConvOperator	The convolutional gradient operator.

Source code in ConvDO/conv_operators.py

def ConvNabla(order: int, device="cpu", dtype=torch.float32):
    r"""
    $\nabla=(\partial p / \partial x,\partial p / \partial y)$ operator. 
    Can be used to compute the gradient of a scalar field or the divergence of a vector field.

    Examples:

        Gradient of a scalar field:
        ```python
        p=ScalarField(torch.rand(1,1,10,10))
        nabla = ConvNabla(order=2, device="cpu", dtype=torch.float32)
        nabla*p # $\nabla p$
        ```

        Divergence of a vector field:
        ```python
        u=VectorValue(ScalarField(torch.rand(1,1,10,10)),ScalarField(torch.rand(1,1,10,10)))
        nabla = ConvNabla(order=2, device="cpu", dtype=torch.float32)
        nabla@u # $\nabla \cdot u$
        ```
    Args:
        order (int): The order of the central interpolation scheme (default is 2).
        device (str, optional): The device to use for computation (default is "cpu").
        dtype (torch.dtype, optional): The data type to use for computation (default is torch.float32).

    Returns:
        ConvOperator (ConvOperator): The convolutional gradient operator.
    """
    return VectorValue(
        ConvOperator(CENTRAL_INTERPOLATION_SCHEMES[order], direction='x', derivative=1, device=device, dtype=dtype), 
        ConvOperator(CENTRAL_INTERPOLATION_SCHEMES[order], direction='y', derivative=1, device=device, dtype=dtype)
        )

ConvDO.conv_operators.ConvGrad2

ConvGrad2(
    order: int = 2,
    direction="x",
    device="cpu",
    dtype=torch.float32,
)

Second order gradient operator \(\partial^2 / \partial x^2\) or \(\partial^2 / \partial y^2\) for a scalar.

Examples:

p=ScalarField(torch.rand(1,1,10,10))
grad_x = ConvGrad2(order=2, direction="x", device="cpu", dtype=torch.float32)
grad_y = ConvGrad2(order=2, direction="y", device="cpu", dtype=torch.float32)
grad_x*p # $\partial^2 p / \partial x^2$ 
grad_y*p # $\partial^2 p / \partial y^2$

Parameters:

Name	Type	Description	Default
order	int	The order of the central Laplacian scheme (default is 2).	2
direction	str	The direction of the gradient operator, ("x" or "y", default is "x").	'x'
device	str	The device to use for computation (default is "cpu").	'cpu'
dtype	dtype	The data type to use for computation (default is torch.float32).	float32

Returns:

Name	Type	Description
ConvOperator	ConvOperator	The convolutional gradient operator.

Source code in ConvDO/conv_operators.py

def ConvGrad2(order: int=2, direction="x", device="cpu", dtype=torch.float32):
    r"""
    Second order gradient operator $\partial^2 / \partial x^2$ or $\partial^2 / \partial y^2$ for a scalar.

    Examples:
        ```python
        p=ScalarField(torch.rand(1,1,10,10))
        grad_x = ConvGrad2(order=2, direction="x", device="cpu", dtype=torch.float32)
        grad_y = ConvGrad2(order=2, direction="y", device="cpu", dtype=torch.float32)
        grad_x*p # $\partial^2 p / \partial x^2$ 
        grad_y*p # $\partial^2 p / \partial y^2$
        ```

    Args:
        order (int): The order of the central Laplacian scheme (default is 2).
        direction (str): The direction of the gradient operator, ("x" or "y", default is "x").
        device (str, optional): The device to use for computation (default is "cpu").
        dtype (torch.dtype, optional): The data type to use for computation (default is torch.float32).

    Returns:
        ConvOperator (ConvOperator): The convolutional gradient operator.
    """
    return ConvOperator(CENTRAL_LAPLACIAN_SCHEMES[order], direction=direction, derivative=2, device=device, dtype=dtype)

ConvDO.conv_operators.ConvLaplacian

Laplacian operator. For scalar field, it is defined as \(\nabla^2 p = \partial^2 p / \partial x^2 + \partial^2 p / \partial y^2\). For vector field, it is defined as \(\nabla \cdot (\nabla \mathbf{u}) = (\frac{\partial u_x }{ \partial x}+\frac{\partial u_x }{ \partial y},\frac{\partial u_y }{ \partial x}+\frac{\partial u_y }{ \partial y})\).

Examples:

Gradient of a scalar field:
```python
p=ScalarField(torch.rand(1,1,10,10))
nabla2 = ConvLaplacian(order=2, device="cpu", dtype=torch.float32)
nabla2*p # $\nabla^2 p$
```

Divergence of a vector field:
```python
u=VectorValue(ScalarField(torch.rand(1,1,10,10)),ScalarField(torch.rand(1,1,10,10)))
nabla2 = ConvLaplacian(order=2, device="cpu", dtype=torch.float32)
nabla*u # $\nabla \cdot (\nabla \mathbf{u})$
```

Parameters:

Name	Type	Description	Default
order	int	The order of the central Laplacian scheme (default is 2).	required
device	str	The device to use for computation (default is "cpu").	'cpu'
dtype	dtype	The data type to use for computation (default is torch.float32).	float32

Returns:

Name	Type	Description
ConvOperator	ConvOperator	The convolutional gradient operator.

Source code in ConvDO/conv_operators.py

class ConvLaplacian():
    r"""
    Laplacian operator. 
    For scalar field, it is defined as $\nabla^2 p = \partial^2 p / \partial x^2 + \partial^2 p / \partial y^2$.
    For vector field, it is defined as $\nabla \cdot (\nabla \mathbf{u}) = (\frac{\partial u_x }{ \partial x}+\frac{\partial u_x }{ \partial y},\frac{\partial u_y }{ \partial x}+\frac{\partial u_y }{ \partial y})$.

    Examples:

        Gradient of a scalar field:
        ```python
        p=ScalarField(torch.rand(1,1,10,10))
        nabla2 = ConvLaplacian(order=2, device="cpu", dtype=torch.float32)
        nabla2*p # $\nabla^2 p$
        ```

        Divergence of a vector field:
        ```python
        u=VectorValue(ScalarField(torch.rand(1,1,10,10)),ScalarField(torch.rand(1,1,10,10)))
        nabla2 = ConvLaplacian(order=2, device="cpu", dtype=torch.float32)
        nabla*u # $\nabla \cdot (\nabla \mathbf{u})$
        ```

    Args:
        order (int): The order of the central Laplacian scheme (default is 2).
        device (str, optional): The device to use for computation (default is "cpu").
        dtype (torch.dtype, optional): The data type to use for computation (default is torch.float32).

    Returns:
        ConvOperator (ConvOperator): The convolutional gradient operator.
    """
    def __init__(self, order: int, device="cpu", dtype=torch.float32) -> None:
        self.op_x = ConvOperator(
            CENTRAL_LAPLACIAN_SCHEMES[order], direction='x', derivative=2, device=device, dtype=dtype)
        self.op_y = ConvOperator(
            CENTRAL_LAPLACIAN_SCHEMES[order], direction='y', derivative=2, device=device, dtype=dtype)

    def __mul__(self, other):
        if isinstance(other, ScalarField):
            return self.op_x*other+self.op_y*other
        elif isinstance(other, VectorValue):
            return VectorValue(
                self.op_x*other.ux+self.op_y*other.ux,
                self.op_x*other.uy+self.op_y*other.uy
            )

op_x instance-attribute

op_x = ConvOperator(
    CENTRAL_LAPLACIAN_SCHEMES[order],
    direction="x",
    derivative=2,
    device=device,
    dtype=dtype,
)

op_y instance-attribute

op_y = ConvOperator(
    CENTRAL_LAPLACIAN_SCHEMES[order],
    direction="y",
    derivative=2,
    device=device,
    dtype=dtype,
)

__init__

__init__(
    order: int, device="cpu", dtype=torch.float32
) -> None

Source code in ConvDO/conv_operators.py

def __init__(self, order: int, device="cpu", dtype=torch.float32) -> None:
    self.op_x = ConvOperator(
        CENTRAL_LAPLACIAN_SCHEMES[order], direction='x', derivative=2, device=device, dtype=dtype)
    self.op_y = ConvOperator(
        CENTRAL_LAPLACIAN_SCHEMES[order], direction='y', derivative=2, device=device, dtype=dtype)

__mul__

__mul__(other)

Source code in ConvDO/conv_operators.py

def __mul__(self, other):
    if isinstance(other, ScalarField):
        return self.op_x*other+self.op_y*other
    elif isinstance(other, VectorValue):
        return VectorValue(
            self.op_x*other.ux+self.op_y*other.ux,
            self.op_x*other.uy+self.op_y*other.uy
        )