Add transformation boundary condition

[connoramoreno]

Description

Adds a transformation boundary condition to surfaces through which the user can define affine transformations to particle position and direction upon crossing the surface.

Mathematically, each affine transformation $\textbf{v} \rightarrow \textbf{v}'$ can be expressed as

$$ \textbf{v}' = A\textbf{v} + \textbf{b} $$

where $A$ is a $3 \times 3$ matrix representing a linear map and $\textbf{b}$ is a vector of length 3 representing a translation. This transformation can be described in a single matrix-vector product via an augmented matrix and augmented vector:

$$ \textbf{v}' = \begin{bmatrix} \textbf{a}_1 & \textbf{a}_2 & \textbf{a}_3 & \textbf{b} \end{bmatrix} \begin{bmatrix} \textbf{v} \\ 1 \end{bmatrix} := [A | \textbf{b}] \begin{bmatrix} \textbf{v} \\ 1 \end{bmatrix} $$

where $\textbf{a}_i$ is the $i^{th}$ column of $A$. I'll refer to this 3x4 augmented matrix $[A | \textbf{b}]$ as an "affine transformation matrix".

In the Python API, the affine transformations are defined by a keyword argument transformation of the Surface class that is used only if boundary_type == "transformation". transformation takes the form of a dictionary with two optional keys:

• "direction": the affine transformation matrix modifying particle direction, given in row-major order
• "position": the affine transformation matrix modifying particle position, given in row-major order

When boundary_type == "transformation", for each key that is not provided, the affine transformation matrix is defined as $[\mathbb{I}_3 | \textbf{0}_3]$, where $\mathbb{I}_3$ is the $3 \times 3$ identity matrix and $\textbf{0}_3$ is the length-3 zero vector.

A single regression test, transformation_plane has been added that mimics the reflective_plane test, replacing the reflective BCs with transformation BCs that apply those same reflections. The expected results file is copied directly from the reflective_plane directory. I can add additional regression tests that mimic the periodic BC tests for more robust testing.

Fixes #3394

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 15) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

[gonuke]

A few streamlining suggestions

[gonuke]

you need to use this msg

[gonuke]

Suggested change

	for key in transformation:
	if key not in ["direction", "position"]:
	valid_keys = {"direction", "position"}
	for key in set(transformation.keys()) - valid_keys:

[gonuke]

Suggested change

	if "direction" in transformation.keys():
	check_type(
	'transformation', transformation["direction"],
	Iterable,
	Real)
	check_length(
	'transformation', transformation["direction"], 12)
	else:
	transformation["direction"] = np.append(
	np.identity(3), np.zeros(3,1), axis=1).flatten()
	if "position" in transformation.keys():
	check_type(
	'transformation', transformation["position"],
	Iterable,
	Real)
	check_length(
	'transformation', transformation["position"], 12)
	else:
	transformation["position"] = np.append(
	np.identity(3), np.zeros(3,1), axis=1).flatten()
	for key in valid_keys
	if key in transformation:
	check_type(
	'transformation', transformation[key],
	Iterable,
	Real)
	check_length(
	'transformation', transformation[key], 12)
	else:
	transformation[key] = np.append(
	np.identity(3), np.zeros(3,1), axis=1).flatten()

[gonuke]

May not be necessary to support two similar keywords

[gonuke]

This may require more thought and consideration