Mondaic

salvus.material.orientation

salvus.material.orientation salvus material orientation

Experimental orientation materials.

Functions

visualize_local_bases()

def visualize_local_bases(
    material: _OrientedMaterial,
    vector_scale: float = 10.0,
    allow_many: bool = False,
) -> Figure: ...

Visualize the local bases rosette of a material.

Helpful for understanding rotations. Works best for only a few orientations.

Parameters
  • material _OrientedMaterial — An orientation material.
  • vector_scale float — Optional scaling passed on to Matplotlib’s quiver.
  • allow_many bool — If True, disables the check on the maximum number of rotations.
Returns Figure — The created matplotlib figure.

Classes

AxesDips

class AxesDips(salvus.material.orientation._OrientedMaterial):
    def __init__(
        self,
        DIP_X: _pd.types.ParameterOrConstantT,
        DIP_Y: _pd.types.ParameterOrConstantT,
    ) -> None: ...

An orientation material parameterized by dip angles in the X and Y direction.

Rotationally (around local Z) ambiguous.

Parameters
  • DIP_X _pd.types.ParameterOrConstantT — Dip away from vertical in the XZ plane, in degrees.
  • DIP_Y _pd.types.ParameterOrConstantT — Dip away from vertical in the YZ plane, in degrees.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Construct this material from another within the same physical system.

Parameters
  • m Material[_pd.types.ParameterFlavorT] — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self — The transformed material.
from_params()
def from_params(
    dip_x: _pd.types.ParameterInput, dip_y: _pd.types.ParameterInput
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • dip_x _pd.types.ParameterInput — Dip away from vertical in the XZ plane, in degrees.
  • dip_y _pd.types.ParameterInput — Dip away from vertical in the YZ plane, in degrees.
Returns typing.Self — The material.
material_system()
def material_system() -> type[Material]: ...

Method that will return the material system of material.

Returns type[Material] — Either the _AcousticMaterial or _ElasticMaterial type.
generate_rotation_matrix()
def generate_rotation_matrix(self) -> npt.NDArray: ...

Create the rotation matrix for this orientation material.

Returns npt.NDArray — A numpy array of the correct shape to orient a material with.
get_basis_vector()
def get_basis_vector(
    self, axis: typing.Literal["local_X", "local_Y", "local_Z"]
) -> npt.NDArray: ...

Gets one of the local basis vectors.

Parameters
  • axis typing.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
Returns npt.NDArray — One of the local basis vectors.
get_basis_vectors()
def get_basis_vectors(
    self,
) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]: ...

Get local basis vectors for a material expressed in global coordinates.

Returns tuple[npt.NDArray, npt.NDArray, npt.NDArray] — A tuple of the local basis vectors.
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimetal method to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

AzimuthDip

class AzimuthDip(salvus.material.orientation._OrientedMaterial):
    def __init__(
        self,
        AZIMUTH: _pd.types.ParameterOrConstantT,
        DIP: _pd.types.ParameterOrConstantT,
    ) -> None: ...

An orientation material parameterized by dip and azimuth.

Rotationally (around local Z) ambiguous.

Parameters
  • AZIMUTH _pd.types.ParameterOrConstantT — Azimuth away from X (towards Y) in degrees.
  • DIP _pd.types.ParameterOrConstantT — Dip away from vertical in degrees,
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Construct this material from another within the same physical system.

Parameters
  • m Material[_pd.types.ParameterFlavorT] — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self — The transformed material.
from_params()
def from_params(
    azimuth: _pd.types.ParameterInput, dip: _pd.types.ParameterInput
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • azimuth _pd.types.ParameterInput — Azimuth away from X (towards Y) in degrees.
  • dip _pd.types.ParameterInput — Dip away from vertical in degrees.
Returns typing.Self — The material.
material_system()
def material_system() -> type[Material]: ...

Method that will return the material system of material.

Returns type[Material] — Either the _AcousticMaterial or _ElasticMaterial type.
generate_rotation_matrix()
def generate_rotation_matrix(self) -> npt.NDArray: ...

Create the rotation matrix for this orientation material.

Returns npt.NDArray — A numpy array of the correct shape to orient a material with.
get_basis_vector()
def get_basis_vector(
    self, axis: typing.Literal["local_X", "local_Y", "local_Z"]
) -> npt.NDArray: ...

Gets one of the local basis vectors.

Parameters
  • axis typing.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
Returns npt.NDArray — One of the local basis vectors.
get_basis_vectors()
def get_basis_vectors(
    self,
) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]: ...

Get local basis vectors for a material expressed in global coordinates.

Returns tuple[npt.NDArray, npt.NDArray, npt.NDArray] — A tuple of the local basis vectors.
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimetal method to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

AzimuthDipRake

class AzimuthDipRake(salvus.material.orientation._OrientedMaterial):
    def __init__(
        self,
        AZIMUTH: _pd.types.ParameterOrConstantT,
        DIP: _pd.types.ParameterOrConstantT,
        RAKE: _pd.types.ParameterOrConstantT,
    ) -> None: ...

An orientation material parameterized by dip, azimuth and rake.

Rake is the intrinsic rotation in degrees about the local Z in the tilt plane. It describes the direction of local X and Y with respect to the strike, i.e. the line on the dipping plane which runs horizontal. It can be understood by “looking” along the azimuthal direction towards the “down” direction. With a rake of 0, this direction is the local X, and to the left (along the horizontal strike of the plane) is the local Y. Rake is measured anticlockwise from this frame (i.e. from local X towards local Y). X being aligned exactly horizontally to the left when looking down the dip plane corresponds to a rake of 90. In global coordinates, the projection of local X and global X have an angle of azimuth + rake.

Parameters
  • AZIMUTH _pd.types.ParameterOrConstantT — Azimuth away from X (towards Y) in degrees.
  • DIP _pd.types.ParameterOrConstantT — Dip away from vertical in degrees.
  • RAKE _pd.types.ParameterOrConstantT — Rake that local X makes away from straight down the dipplane in degrees. 0 is straight down the dip plane, 90 is horizontal to the left (anticlockwise) of the dip plane, when looking down the dip plane. This is an intrinsic angle, and the direction of local X and Y will be determined by the combination of azimuth and rake.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Construct this material from another within the same physical system.

Parameters
  • m Material[_pd.types.ParameterFlavorT] — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self — The transformed material.
from_params()
def from_params(
    azimuth: _pd.types.ParameterInput,
    dip: _pd.types.ParameterInput,
    rake: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • azimuth _pd.types.ParameterInput — Azimuth away from global X (towards Y) in degrees.
  • dip _pd.types.ParameterInput — Dip away from vertical in degrees.
  • rake _pd.types.ParameterInput — Rake that local X makes away from straight down the dipplane in degrees. 0 is straight down the dip plane, 90 is horizontal to the left (anticlockwise) of the dip plane, when looking down the dip plane.
Returns typing.Self — The material.
material_system()
def material_system() -> type[Material]: ...

Method that will return the material system of material.

Returns type[Material] — Either the _AcousticMaterial or _ElasticMaterial type.
generate_rotation_matrix()
def generate_rotation_matrix(self) -> npt.NDArray: ...

Create the rotation matrix for this orientation material.

Returns npt.NDArray — A numpy array of the correct shape to orient a material with.
get_basis_vector()
def get_basis_vector(
    self, axis: typing.Literal["local_X", "local_Y", "local_Z"]
) -> npt.NDArray: ...

Gets one of the local basis vectors.

Parameters
  • axis typing.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
Returns npt.NDArray — One of the local basis vectors.
get_basis_vectors()
def get_basis_vectors(
    self,
) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]: ...

Get local basis vectors for a material expressed in global coordinates.

Returns tuple[npt.NDArray, npt.NDArray, npt.NDArray] — A tuple of the local basis vectors.
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimetal method to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

ClockwiseAngle

class ClockwiseAngle(salvus.material.orientation._OrientedMaterial):
    def __init__(
        self, ANGLE_IN_DEGREES: _pd.types.ParameterOrConstantT
    ) -> None: ...

An orientation material parameterized by a clockwise rotation angle.

Only useful for 2-D materials.

Parameters
  • ANGLE_IN_DEGREES _pd.types.ParameterOrConstantT — The clockwise rotation angle in degree.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Construct this material from another within the same physical system.

Parameters
  • m Material[_pd.types.ParameterFlavorT] — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self — The transformed material.
from_params()
def from_params(angle_in_degrees: _pd.types.ParameterInput) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • angle_in_degrees _pd.types.ParameterInput — The clockwise rotation angle in degree.
Returns typing.Self — The material.
material_system()
def material_system() -> type[Material]: ...

Method that will return the material system of material.

Returns type[Material] — Either the _AcousticMaterial or _ElasticMaterial type.
generate_rotation_matrix()
def generate_rotation_matrix(self) -> npt.NDArray: ...

Create the rotation matrix for this orientation material.

Returns npt.NDArray — A numpy array of the correct shape to orient a material with.
get_basis_vector()
def get_basis_vector(
    self, axis: typing.Literal["local_X", "local_Y", "local_Z"]
) -> npt.NDArray: ...

Gets one of the local basis vectors.

Parameters
  • axis typing.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
Returns npt.NDArray — One of the local basis vectors.
get_basis_vectors()
def get_basis_vectors(
    self,
) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]: ...

Get local basis vectors for a material expressed in global coordinates.

Returns tuple[npt.NDArray, npt.NDArray, npt.NDArray] — A tuple of the local basis vectors.
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimetal method to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

DirectOrthonormalBasis

class DirectOrthonormalBasis(salvus.material.orientation._OrientedMaterial):
    def __init__(
        self,
        M00: _pd.types.ParameterOrConstantT,
        M01: _pd.types.ParameterOrConstantT,
        M02: _pd.types.ParameterOrConstantT,
        M10: _pd.types.ParameterOrConstantT,
        M11: _pd.types.ParameterOrConstantT,
        M12: _pd.types.ParameterOrConstantT,
        M20: _pd.types.ParameterOrConstantT,
        M21: _pd.types.ParameterOrConstantT,
        M22: _pd.types.ParameterOrConstantT,
    ) -> None: ...

Orientation given directly by an orthonormal basis matrix.

The basis vectors are given in the order local_X, local_Y, local_Z. The basis vectors are assumed to be orthonormal and right-handed. The orientation is given by the rotation matrix that transforms the global basis vectors to the local basis vectors.

By default, Gram-Schmidt (GS) orthonormalization is applied to the input vectors to ensure they are orthonormal and right-handed, even if the input vectors are only approximately so (e.g., due to numerical error). This is recommended unless you are certain your input vectors are already exactly orthonormal and right-handed, in which case you can disable GS by setting skip_orthonormalization=True on various constructors for improved performance and to preserve the original vectors exactly.

  • If GS is enabled (the default), the input vectors will be orthonormalized in the order local_X, local_Y, local_Z.
  • If GS is disabled, the input vectors are used as-is, and it is the caller’s responsibility to ensure they are orthonormal and right-handed.
Parameters
  • M00 _pd.types.ParameterOrConstantT — The first component of the first basis vector.
  • M01 _pd.types.ParameterOrConstantT — The second component of the first basis vector.
  • M02 _pd.types.ParameterOrConstantT — The third component of the first basis vector.
  • M10 _pd.types.ParameterOrConstantT — The first component of the second basis vector.
  • M11 _pd.types.ParameterOrConstantT — The second component of the second basis vector.
  • M12 _pd.types.ParameterOrConstantT — The third component of the second basis vector.
  • M20 _pd.types.ParameterOrConstantT — The first component of the third basis vector.
  • M21 _pd.types.ParameterOrConstantT — The second component of the third basis vector.
  • M22 _pd.types.ParameterOrConstantT — The third component of the third basis vector.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

Methods
from_array()
def from_array(
    matrix: npt.NDArray, skip_orthonormalization: bool = False
) -> typing.Self: ...

Construct this material from a 3x3 matrix or array of matrices.

Parameters
  • matrix npt.NDArray — A 3x3 matrix or array of matrices that represent the local basis vectors.
  • skip_orthonormalization bool — If True, the Gram-Schmidt orthonormalization procedure is skipped. This is useful if one is sure that the input vectors are already orthonormal. If False, the Gram-Schmidt orthonormalization procedure is applied to the input vectors. Gram-Schmidt orthonormalization applied in m0, m1, m2 order.
Returns typing.Self — The material.
from_basis_vectors()
def from_basis_vectors(
    local_x: npt.NDArray,
    local_y: npt.NDArray,
    local_z: npt.NDArray,
    skip_orthonormalization: bool = False,
) -> typing.Self: ...

Construct from three orthonormal basis vectors.

Parameters
  • local_x npt.NDArray — The first basis vector.
  • local_y npt.NDArray — The second basis vector.
  • local_z npt.NDArray — The third basis vector.
  • skip_orthonormalization bool — If True, the Gram-Schmidt orthonormalization procedure is skipped. This is useful if one is sure that the input vectors are already orthonormal. If False, the Gram-Schmidt orthonormalization procedure is applied to the input vectors. Gram-Schmidt orthonormalization applied in m0, m1, m2 order.
Returns typing.Self — The material.
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Construct this material from another within the same physical system.

Parameters
  • m Material[_pd.types.ParameterFlavorT] — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self — The transformed material.
from_params()
def from_params(
    m00: _pd.types.ParameterInput,
    m01: _pd.types.ParameterInput,
    m02: _pd.types.ParameterInput,
    m10: _pd.types.ParameterInput,
    m11: _pd.types.ParameterInput,
    m12: _pd.types.ParameterInput,
    m20: _pd.types.ParameterInput,
    m21: _pd.types.ParameterInput,
    m22: _pd.types.ParameterInput,
    skip_orthonormalization: bool = False,
) -> typing.Self: ...

Construct from nine scalar matrix components.

Parameters
  • m00 _pd.types.ParameterInput — The first component of the first basis vector.
  • m01 _pd.types.ParameterInput — The second component of the first basis vector.
  • m02 _pd.types.ParameterInput — The third component of the first basis vector.
  • m10 _pd.types.ParameterInput — The first component of the second basis vector.
  • m11 _pd.types.ParameterInput — The second component of the second basis vector.
  • m12 _pd.types.ParameterInput — The third component of the second basis vector.
  • m20 _pd.types.ParameterInput — The first component of the third basis vector.
  • m21 _pd.types.ParameterInput — The second component of the third basis vector.
  • m22 _pd.types.ParameterInput — The third component of the third basis vector.
  • skip_orthonormalization bool — If True, the Gram-Schmidt orthonormalization procedure is skipped. This is useful if one is sure that the input vectors are already orthonormal. If False, the Gram-Schmidt orthonormalization procedure is applied to the input vectors. Gram-Schmidt orthonormalization applied in m0, m1, m2 order.
Returns typing.Self — The material.
material_system()
def material_system() -> type[Material]: ...

Method that will return the material system of material.

Returns type[Material] — Either the _AcousticMaterial or _ElasticMaterial type.
generate_rotation_matrix()
def generate_rotation_matrix(self) -> npt.NDArray: ...

Reconstruct the rotation matrix from stored components.

Returns npt.NDArray
get_basis_vector()
def get_basis_vector(
    self, axis: typing.Literal["local_X", "local_Y", "local_Z"]
) -> npt.NDArray: ...

Gets one of the local basis vectors.

Parameters
  • axis typing.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
Returns npt.NDArray — One of the local basis vectors.
get_basis_vectors()
def get_basis_vectors(
    self,
) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]: ...

Get local basis vectors for a material expressed in global coordinates.

Returns tuple[npt.NDArray, npt.NDArray, npt.NDArray] — A tuple of the local basis vectors.
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimetal method to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

Used in tutorials