salvus.material.orientation
salvus.material.orientation salvus material orientation Experimental orientation materials.
Functions
visualize_local_bases()
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.
material_OrientedMaterial — An orientation material.vector_scalefloat =10.0— Optional scaling passed on to Matplotlib’s quiver.allow_manybool =False— If True, disables the check on the maximum number of rotations.
Classes
AxesDips
AxesDipsclass AxesDips(salvus.material.orientation._OrientedMaterial):
def __init__(
self,
DIP_X: _pd.types.ParameterOrConstantT,
DIP_Y: _pd.types.ParameterOrConstantT,
extensions: typing.Mapping[str, Material] = default,
) -> None: ...An orientation material parameterized by dip angles in the X and Y direction.
Rotationally (around local Z) ambiguous.
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.extensionstyping.Mapping[str, Material] =<factory>— Attached extension materials. This material supports none, so this must stay empty.
attenuation Material | None
attenuation Material | NoneOptional attenuation extension.
ds typing.Mapping
ds typing.MappingMaterial’s xarray representation.
flatten dict
flatten dictGet all parameters as a dict, including extension parameters.
orientation Material | None
orientation Material | NoneOptional orientation extension.
from_dataset()
from_dataset()def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...Construct a material from an xarray Dataset.
dsxr.Dataset — The dataset to construct the material from.
from_json()
from_json()def from_json(d: Dict) -> Any: ...Recreate the object from a dictionary serialization of its initialization parameters.
Only load trusted input.
dDict — Dictionary containing its init parameters and a few other things.
from_material()
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.
mMaterial[_pd.types.ParameterFlavorT] — Material to transform.reduction_methodtyping.Literal['remove-components', 'force'] | None =None— Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, whileremove-componentswill 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.
from_params()
from_params()def from_params(
dip_x: _pd.types.ParameterInput, dip_y: _pd.types.ParameterInput
) -> typing.Self: ...Construct this material from generic 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.
material_system()
material_system()def material_system() -> type[Material]: ...Method that will return the material system of material.
generate_rotation_matrix()
generate_rotation_matrix()def generate_rotation_matrix(self) -> npt.NDArray: ...Create the rotation matrix for this orientation material.
get_basis_vector()
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.
axistyping.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
get_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.
map()
map()def map(
self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> Self: ...Generic map for materials, recursing into extension materials.
See dataclass_utils.MappableDataclass.map for the base semantics.
Extension materials (in extensions) are mapped independently, since
f is defined in terms of a single material’s own parameter names.
ftyping.Callable[[str, typing.Any], tuple[str, typing.Any]] — Callable taking (key, value) and returning (key, value).
map_realized_parameters()
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.
f_constanttyping.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to constant parameters. Defaults to returning the parameter as-is.f_discretetyping.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to discrete parameters. Defaults to returning the parameter as-is.f_analytictyping.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to analytic parameters. Defaults to returning the parameter as-is.
qc_test()
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.
levelvalidation.QCLevel | str =QCLevel.strict— 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_issuesbool =True— If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
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()
to_json()def to_json(
self,
external_file_hash: Optional[str] = None,
timer: Optional[salvus._core.timer.timer.Timer] = None,
log_to_logger: bool = False,
comm: Optional[int] = None,
) -> Dict: ...Serialize the object to a dictionary that can be written to JSON.
external_file_hashOptional[str] =None— 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.timerOptional[salvus._core.timer.timer.Timer] =None— Execution timer.log_to_loggerbool =False— Log timings to the logger.commOptional[int] =None— MPI communicator, if any.
to_wavelength_oracle()
to_wavelength_oracle()def to_wavelength_oracle(
self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...The wavelength oracle.
n_dimtyping.Literal[2, 3] | None =None— Dimension to return the oracle for, deprecated.
with_extension()
with_extension()def with_extension(self, name: str, value: Material | None) -> Self: ...Attach or detach an extension material by name.
Passing value=None always removes the extension, even if name
isn’t in _supported_extensions (mirrors removing something that
was never there). Attaching a real value that isn’t supported
raises, as does constructing the material with it directly.
namestr — Extension name (e.g.,"attenuation","orientation").valueMaterial | None — Extension material, orNoneto remove.
AzimuthDip
AzimuthDipclass AzimuthDip(salvus.material.orientation._OrientedMaterial):
def __init__(
self,
AZIMUTH: _pd.types.ParameterOrConstantT,
DIP: _pd.types.ParameterOrConstantT,
extensions: typing.Mapping[str, Material] = default,
) -> None: ...An orientation material parameterized by dip and azimuth.
Rotationally (around local Z) ambiguous.
AZIMUTH_pd.types.ParameterOrConstantT — Azimuth away from X (towards Y) in degrees.DIP_pd.types.ParameterOrConstantT — Dip away from vertical in degrees,extensionstyping.Mapping[str, Material] =<factory>— Attached extension materials. This material supports none, so this must stay empty.
attenuation Material | None
attenuation Material | NoneOptional attenuation extension.
ds typing.Mapping
ds typing.MappingMaterial’s xarray representation.
flatten dict
flatten dictGet all parameters as a dict, including extension parameters.
orientation Material | None
orientation Material | NoneOptional orientation extension.
from_dataset()
from_dataset()def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...Construct a material from an xarray Dataset.
dsxr.Dataset — The dataset to construct the material from.
from_json()
from_json()def from_json(d: Dict) -> Any: ...Recreate the object from a dictionary serialization of its initialization parameters.
Only load trusted input.
dDict — Dictionary containing its init parameters and a few other things.
from_material()
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.
mMaterial[_pd.types.ParameterFlavorT] — Material to transform.reduction_methodtyping.Literal['remove-components', 'force'] | None =None— Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, whileremove-componentswill 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.
from_params()
from_params()def from_params(
azimuth: _pd.types.ParameterInput, dip: _pd.types.ParameterInput
) -> typing.Self: ...Construct this material from generic parameters.
azimuth_pd.types.ParameterInput — Azimuth away from X (towards Y) in degrees.dip_pd.types.ParameterInput — Dip away from vertical in degrees.
material_system()
material_system()def material_system() -> type[Material]: ...Method that will return the material system of material.
generate_rotation_matrix()
generate_rotation_matrix()def generate_rotation_matrix(self) -> npt.NDArray: ...Create the rotation matrix for this orientation material.
get_basis_vector()
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.
axistyping.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
get_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.
map()
map()def map(
self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> Self: ...Generic map for materials, recursing into extension materials.
See dataclass_utils.MappableDataclass.map for the base semantics.
Extension materials (in extensions) are mapped independently, since
f is defined in terms of a single material’s own parameter names.
ftyping.Callable[[str, typing.Any], tuple[str, typing.Any]] — Callable taking (key, value) and returning (key, value).
map_realized_parameters()
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.
f_constanttyping.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to constant parameters. Defaults to returning the parameter as-is.f_discretetyping.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to discrete parameters. Defaults to returning the parameter as-is.f_analytictyping.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to analytic parameters. Defaults to returning the parameter as-is.
qc_test()
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.
levelvalidation.QCLevel | str =QCLevel.strict— 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_issuesbool =True— If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
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()
to_json()def to_json(
self,
external_file_hash: Optional[str] = None,
timer: Optional[salvus._core.timer.timer.Timer] = None,
log_to_logger: bool = False,
comm: Optional[int] = None,
) -> Dict: ...Serialize the object to a dictionary that can be written to JSON.
external_file_hashOptional[str] =None— 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.timerOptional[salvus._core.timer.timer.Timer] =None— Execution timer.log_to_loggerbool =False— Log timings to the logger.commOptional[int] =None— MPI communicator, if any.
to_wavelength_oracle()
to_wavelength_oracle()def to_wavelength_oracle(
self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...The wavelength oracle.
n_dimtyping.Literal[2, 3] | None =None— Dimension to return the oracle for, deprecated.
with_extension()
with_extension()def with_extension(self, name: str, value: Material | None) -> Self: ...Attach or detach an extension material by name.
Passing value=None always removes the extension, even if name
isn’t in _supported_extensions (mirrors removing something that
was never there). Attaching a real value that isn’t supported
raises, as does constructing the material with it directly.
namestr — Extension name (e.g.,"attenuation","orientation").valueMaterial | None — Extension material, orNoneto remove.
AzimuthDipRake
AzimuthDipRakeclass AzimuthDipRake(salvus.material.orientation._OrientedMaterial):
def __init__(
self,
AZIMUTH: _pd.types.ParameterOrConstantT,
DIP: _pd.types.ParameterOrConstantT,
RAKE: _pd.types.ParameterOrConstantT,
extensions: typing.Mapping[str, Material] = default,
) -> 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.
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.extensionstyping.Mapping[str, Material] =<factory>— Attached extension materials. This material supports none, so this must stay empty.
attenuation Material | None
attenuation Material | NoneOptional attenuation extension.
ds typing.Mapping
ds typing.MappingMaterial’s xarray representation.
flatten dict
flatten dictGet all parameters as a dict, including extension parameters.
orientation Material | None
orientation Material | NoneOptional orientation extension.
from_dataset()
from_dataset()def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...Construct a material from an xarray Dataset.
dsxr.Dataset — The dataset to construct the material from.
from_json()
from_json()def from_json(d: Dict) -> Any: ...Recreate the object from a dictionary serialization of its initialization parameters.
Only load trusted input.
dDict — Dictionary containing its init parameters and a few other things.
from_material()
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.
mMaterial[_pd.types.ParameterFlavorT] — Material to transform.reduction_methodtyping.Literal['remove-components', 'force'] | None =None— Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, whileremove-componentswill 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.
from_params()
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.
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.
material_system()
material_system()def material_system() -> type[Material]: ...Method that will return the material system of material.
generate_rotation_matrix()
generate_rotation_matrix()def generate_rotation_matrix(self) -> npt.NDArray: ...Create the rotation matrix for this orientation material.
get_basis_vector()
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.
axistyping.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
get_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.
map()
map()def map(
self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> Self: ...Generic map for materials, recursing into extension materials.
See dataclass_utils.MappableDataclass.map for the base semantics.
Extension materials (in extensions) are mapped independently, since
f is defined in terms of a single material’s own parameter names.
ftyping.Callable[[str, typing.Any], tuple[str, typing.Any]] — Callable taking (key, value) and returning (key, value).
map_realized_parameters()
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.
f_constanttyping.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to constant parameters. Defaults to returning the parameter as-is.f_discretetyping.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to discrete parameters. Defaults to returning the parameter as-is.f_analytictyping.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to analytic parameters. Defaults to returning the parameter as-is.
qc_test()
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.
levelvalidation.QCLevel | str =QCLevel.strict— 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_issuesbool =True— If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
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()
to_json()def to_json(
self,
external_file_hash: Optional[str] = None,
timer: Optional[salvus._core.timer.timer.Timer] = None,
log_to_logger: bool = False,
comm: Optional[int] = None,
) -> Dict: ...Serialize the object to a dictionary that can be written to JSON.
external_file_hashOptional[str] =None— 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.timerOptional[salvus._core.timer.timer.Timer] =None— Execution timer.log_to_loggerbool =False— Log timings to the logger.commOptional[int] =None— MPI communicator, if any.
to_wavelength_oracle()
to_wavelength_oracle()def to_wavelength_oracle(
self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...The wavelength oracle.
n_dimtyping.Literal[2, 3] | None =None— Dimension to return the oracle for, deprecated.
with_extension()
with_extension()def with_extension(self, name: str, value: Material | None) -> Self: ...Attach or detach an extension material by name.
Passing value=None always removes the extension, even if name
isn’t in _supported_extensions (mirrors removing something that
was never there). Attaching a real value that isn’t supported
raises, as does constructing the material with it directly.
namestr — Extension name (e.g.,"attenuation","orientation").valueMaterial | None — Extension material, orNoneto remove.
ClockwiseAngle
ClockwiseAngleclass ClockwiseAngle(salvus.material.orientation._OrientedMaterial):
def __init__(
self,
ANGLE_IN_DEGREES: _pd.types.ParameterOrConstantT,
extensions: typing.Mapping[str, Material] = default,
) -> None: ...An orientation material parameterized by a clockwise rotation angle.
Only useful for 2-D materials.
ANGLE_IN_DEGREES_pd.types.ParameterOrConstantT — The clockwise rotation angle in degree.extensionstyping.Mapping[str, Material] =<factory>— Attached extension materials. This material supports none, so this must stay empty.
attenuation Material | None
attenuation Material | NoneOptional attenuation extension.
ds typing.Mapping
ds typing.MappingMaterial’s xarray representation.
flatten dict
flatten dictGet all parameters as a dict, including extension parameters.
orientation Material | None
orientation Material | NoneOptional orientation extension.
from_dataset()
from_dataset()def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...Construct a material from an xarray Dataset.
dsxr.Dataset — The dataset to construct the material from.
from_json()
from_json()def from_json(d: Dict) -> Any: ...Recreate the object from a dictionary serialization of its initialization parameters.
Only load trusted input.
dDict — Dictionary containing its init parameters and a few other things.
from_material()
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.
mMaterial[_pd.types.ParameterFlavorT] — Material to transform.reduction_methodtyping.Literal['remove-components', 'force'] | None =None— Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, whileremove-componentswill 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.
from_params()
from_params()def from_params(angle_in_degrees: _pd.types.ParameterInput) -> typing.Self: ...Construct this material from generic parameters.
angle_in_degrees_pd.types.ParameterInput — The clockwise rotation angle in degree.
material_system()
material_system()def material_system() -> type[Material]: ...Method that will return the material system of material.
generate_rotation_matrix()
generate_rotation_matrix()def generate_rotation_matrix(self) -> npt.NDArray: ...Create the rotation matrix for this orientation material.
get_basis_vector()
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.
axistyping.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
get_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.
map()
map()def map(
self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> Self: ...Generic map for materials, recursing into extension materials.
See dataclass_utils.MappableDataclass.map for the base semantics.
Extension materials (in extensions) are mapped independently, since
f is defined in terms of a single material’s own parameter names.
ftyping.Callable[[str, typing.Any], tuple[str, typing.Any]] — Callable taking (key, value) and returning (key, value).
map_realized_parameters()
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.
f_constanttyping.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to constant parameters. Defaults to returning the parameter as-is.f_discretetyping.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to discrete parameters. Defaults to returning the parameter as-is.f_analytictyping.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to analytic parameters. Defaults to returning the parameter as-is.
qc_test()
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.
levelvalidation.QCLevel | str =QCLevel.strict— 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_issuesbool =True— If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
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()
to_json()def to_json(
self,
external_file_hash: Optional[str] = None,
timer: Optional[salvus._core.timer.timer.Timer] = None,
log_to_logger: bool = False,
comm: Optional[int] = None,
) -> Dict: ...Serialize the object to a dictionary that can be written to JSON.
external_file_hashOptional[str] =None— 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.timerOptional[salvus._core.timer.timer.Timer] =None— Execution timer.log_to_loggerbool =False— Log timings to the logger.commOptional[int] =None— MPI communicator, if any.
to_wavelength_oracle()
to_wavelength_oracle()def to_wavelength_oracle(
self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...The wavelength oracle.
n_dimtyping.Literal[2, 3] | None =None— Dimension to return the oracle for, deprecated.
with_extension()
with_extension()def with_extension(self, name: str, value: Material | None) -> Self: ...Attach or detach an extension material by name.
Passing value=None always removes the extension, even if name
isn’t in _supported_extensions (mirrors removing something that
was never there). Attaching a real value that isn’t supported
raises, as does constructing the material with it directly.
namestr — Extension name (e.g.,"attenuation","orientation").valueMaterial | None — Extension material, orNoneto remove.
DirectOrthonormalBasis
DirectOrthonormalBasisclass 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,
extensions: typing.Mapping[str, Material] = default,
) -> 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.
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.extensionstyping.Mapping[str, Material] =<factory>— Attached extension materials. This material supports none, so this must stay empty.
attenuation Material | None
attenuation Material | NoneOptional attenuation extension.
ds typing.Mapping
ds typing.MappingMaterial’s xarray representation.
flatten dict
flatten dictGet all parameters as a dict, including extension parameters.
orientation Material | None
orientation Material | NoneOptional orientation extension.
from_array()
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.
matrixnpt.NDArray — A 3x3 matrix or array of matrices that represent the local basis vectors.skip_orthonormalizationbool =False— 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.
from_basis_vectors()
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.
local_xnpt.NDArray — The first basis vector.local_ynpt.NDArray — The second basis vector.local_znpt.NDArray — The third basis vector.skip_orthonormalizationbool =False— 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.
from_dataset()
from_dataset()def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...Construct a material from an xarray Dataset.
dsxr.Dataset — The dataset to construct the material from.
from_json()
from_json()def from_json(d: Dict) -> Any: ...Recreate the object from a dictionary serialization of its initialization parameters.
Only load trusted input.
dDict — Dictionary containing its init parameters and a few other things.
from_material()
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.
mMaterial[_pd.types.ParameterFlavorT] — Material to transform.reduction_methodtyping.Literal['remove-components', 'force'] | None =None— Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, whileremove-componentswill 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.
from_params()
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.
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_orthonormalizationbool =False— 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.
material_system()
material_system()def material_system() -> type[Material]: ...Method that will return the material system of material.
generate_rotation_matrix()
generate_rotation_matrix()def generate_rotation_matrix(self) -> npt.NDArray: ...Reconstruct the rotation matrix from stored components.
get_basis_vector()
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.
axistyping.Literal['local_X', 'local_Y', 'local_Z'] — The local basis vector to get.
get_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.
map()
map()def map(
self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> Self: ...Generic map for materials, recursing into extension materials.
See dataclass_utils.MappableDataclass.map for the base semantics.
Extension materials (in extensions) are mapped independently, since
f is defined in terms of a single material’s own parameter names.
ftyping.Callable[[str, typing.Any], tuple[str, typing.Any]] — Callable taking (key, value) and returning (key, value).
map_realized_parameters()
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.
f_constanttyping.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to constant parameters. Defaults to returning the parameter as-is.f_discretetyping.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to discrete parameters. Defaults to returning the parameter as-is.f_analytictyping.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] =salvus.material.base_materials._map_realized_default— The function to apply to analytic parameters. Defaults to returning the parameter as-is.
qc_test()
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.
levelvalidation.QCLevel | str =QCLevel.strict— 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_issuesbool =True— If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
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()
to_json()def to_json(
self,
external_file_hash: Optional[str] = None,
timer: Optional[salvus._core.timer.timer.Timer] = None,
log_to_logger: bool = False,
comm: Optional[int] = None,
) -> Dict: ...Serialize the object to a dictionary that can be written to JSON.
external_file_hashOptional[str] =None— 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.timerOptional[salvus._core.timer.timer.Timer] =None— Execution timer.log_to_loggerbool =False— Log timings to the logger.commOptional[int] =None— MPI communicator, if any.
to_wavelength_oracle()
to_wavelength_oracle()def to_wavelength_oracle(
self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...The wavelength oracle.
n_dimtyping.Literal[2, 3] | None =None— Dimension to return the oracle for, deprecated.
with_extension()
with_extension()def with_extension(self, name: str, value: Material | None) -> Self: ...Attach or detach an extension material by name.
Passing value=None always removes the extension, even if name
isn’t in _supported_extensions (mirrors removing something that
was never there). Attaching a real value that isn’t supported
raises, as does constructing the material with it directly.
namestr — Extension name (e.g.,"attenuation","orientation").valueMaterial | None — Extension material, orNoneto remove.