simulation.compute
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
Where an FDTD simulation runs: the device, its dtype and what to do if absent.
A Compute record is a request. Building one imports and probes
nothing, so a record naming a GPU can be written on a machine without one;
the engine checks the request when it is built. The request comes from the
compute= argument, else from the innermost use block, else from
the PHONOMETRY_COMPUTE environment variable, else it is NumPy in float64.
use holds its record in a context variable. Whether a new thread or
process sees it depends on how it is started; give a worker its placement
through compute= or PHONOMETRY_COMPUTE.
The environment variable is read when a computation resolves its placement,
never at import. Its grammar is device[:index][@host][,option...] with the
options float32, float64 and fallback: cupy, cupy:1,
torch:cuda:1,fallback, torch:mps,float32, cupy@nas. A host is a
name in the hosts file (see the guide on remote nodes); only the two
simulation functions, fdtd_simulation and
elastic_fdtd_simulation, and the two video
writers, write_fdtd_animation and
write_elastic_fdtd_animation, run on one.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
Compute
Section titled “Compute”Compute( *, device: Literal['cpu', 'cupy', 'torch:cpu', 'torch:cuda', 'torch:mps'] = 'cpu', device_index: int | np.integer[Any] = 0, dtype: Literal['float64', 'float32'] = 'float64', fallback: bool | np.bool_ = False, host: str | None = None, timeout_s: float | None = None,)Where an FDTD simulation steps, in which dtype, and whether it may fall back.
Parameters
| Name | Description |
|---|---|
device |
The array library and device: "cpu" (NumPy, the default), "cupy" (an NVIDIA GPU through CuPy), "torch:cpu", "torch:cuda" or "torch:mps" (Apple silicon, float32 only). |
device_index |
Which GPU, for "cupy" and "torch:cuda". |
dtype |
"float64" (default) or "float32". |
fallback |
Run on NumPy here, with a ComputeFallbackWarning, when the device is not available or, for a run with a host, when the node or the connection fails, instead of raising. |
host |
The node the run goes to, by its name in the hosts file, or None (default) to run on this machine. Only fdtd_simulation, elastic_fdtd_simulation and the two video writers, write_fdtd_animation and write_elastic_fdtd_animation, run on a node; an engine built here refuses a host. |
timeout_s |
The longest a remote run may take, from connecting to the result [s], or None for the hosts file’s value (no limit when the file names none). Only with a host. |
Raises
| Exception | When |
|---|---|
| TypeError | for a device or dtype that is not text, a device_index that is not a number (a bool is not one), a fallback that is not True or False, a host that is neither text nor None, or a timeout_s that is not one number. |
| ValueError | for an unknown device or dtype, "torch:mps" in float64, an index on a device that has one instance, an index that is not a whole number of 0 or more, a host that is not a name the hosts file can hold, a timeout_s without a host, not positive or longer than a timer here can wait (threading.TIMEOUT_MAX), or a fallback asked of "cpu" on this machine. |
ComputeDeviceError
Section titled “ComputeDeviceError”A requested device is not present or cannot be used.
ComputeFallbackWarning
Section titled “ComputeFallbackWarning”A requested device or node could not be used and the run went to NumPy here.
ComputeImportError
Section titled “ComputeImportError”The library a requested device needs is not installed, or does not import.
ComputeRemoteError
Section titled “ComputeRemoteError”A run sent to a node failed in the connection or on the node.
Raised for a transport failure (no ssh client on PATH, where on
Windows one in the working directory does not count, a node that cannot
be reached, a stream that breaks the protocol, a run past its timeout) and
for a failure on the node (an image or a Python environment that cannot
run the package, an exception raised by the run itself). A wrong
argument is never one: it raises its own TypeError or ValueError
before anything connects.
Attributes
| Name | Description |
|---|---|
host |
The node’s name in the hosts file. |
node_traceback |
The traceback the node printed, as text, when the run raised there; it is also attached as a note, so a traceback printed here shows it. |
RunProvenance
Section titled “RunProvenance”RunProvenance( *, host: str | None, device: Literal['cpu', 'cupy', 'torch:cpu', 'torch:cuda', 'torch:mps'], device_index: int, dtype: Literal['float64', 'float32'], phonometry_version: str, numpy_version: str, array_library: str | None, cuda_runtime: str | None, cuda_driver_api: str | None, gpu: str | None, package_sha256: str | None,)Where a run actually stepped, recorded by the result.
Attributes
| Name | Description |
|---|---|
host |
The node the run went to, or None for this machine. |
device |
The device that stepped the fields. One of "cpu", "cupy", "torch:cpu", "torch:cuda" or "torch:mps". |
device_index |
Which GPU, 0 where there is one. |
dtype |
The dtype of the fields. One of "float64" or "float32". |
phonometry_version |
The version of the phonometry that ran the steps (phonometry.__version__); on a node, the client’s own, whose package the node runs. |
numpy_version |
NumPy’s version where the run stepped. |
array_library |
The array library and its version ("cupy 14.2.0"), or None for NumPy. |
cuda_runtime |
The CUDA runtime the array library uses, as "major.minor" ("13.2"), or None off a CUDA device. |
cuda_driver_api |
The CUDA version the GPU driver supports, as "major.minor" ("13.3"), where the array library reports it (CuPy), else None. It is not the NVIDIA driver’s own version. |
gpu |
The GPU’s name, or None. |
package_sha256 |
The SHA-256 of the package the node ran, in lowercase hex, or None for a run on this machine. |
Raises
| Exception | When |
|---|---|
| TypeError | for a device or dtype that is not text, a device_index that is not a number (a bool is not one), a phonometry_version or numpy_version that is not text, or a host, array_library, cuda_runtime, cuda_driver_api, gpu or package_sha256 that is neither text nor None. |
| ValueError | for an unknown device or dtype, "torch:mps" in float64, an index on a device that has one instance, an index that is not a whole number of 0 or more, or a package_sha256 that is not 64 lowercase hexadecimal digits. |
use(compute: Compute) -> Iterator[Compute]Make compute the placement of every simulation built in this block.
The record lives in a context variable. Whether a new thread or process
sees it depends on how it is started; give a worker its placement through
compute= or PHONOMETRY_COMPUTE.
Parameters
| Name | Description |
|---|---|
compute |
The placement. |
Raises
| Exception | When |
|---|---|
| TypeError | for anything but a Compute. |