torchphysics.utils package

Useful helper methods for the definition and evaluation of a problem.

For the creation of conditions, some differential operators are implemented under torchphysics.utils.differentialoperators.

For the evaluation of the trained model, some plot and animation functionalities are provided. They can give you a rough overview of the determined solution. These lay under torchphysics.utils.plotting

Subpackages

• torchphysics.utils.data package
  • Submodules
  • torchphysics.utils.data.dataloader module
    • PointsDataLoader
    • PointsDataset
      • PointsDataset.__getitem__()
      • PointsDataset.__len__()
  • torchphysics.utils.data.deeponet_dataloader module
    • DeepONetDataLoader
    • DeepONetDataset
      • DeepONetDataset.__getitem__()
      • DeepONetDataset.__len__()
    • DeepONetDataset_Unique
      • DeepONetDataset_Unique.__getitem__()
      • DeepONetDataset_Unique.__len__()
• torchphysics.utils.plotting package
  • Submodules
  • torchphysics.utils.plotting.animation module
    • animate()
    • animation_contour_2D()
    • animation_line()
    • animation_quiver_2D()
    • animation_surface2D()
  • torchphysics.utils.plotting.plot_functions module
    • Plotter
      • Plotter.plot()
    • contour_2D()
    • curve3D()
    • line_plot()
    • plot()
    • quiver2D()
    • surface2D()
  • torchphysics.utils.plotting.scatter_points module
    • scatter()

Submodules

torchphysics.utils.callbacks module

class torchphysics.utils.callbacks.PlotterCallback(model, plot_function, point_sampler, log_name='plot', check_interval=200, angle=[30, 30], plot_type='', **kwargs)

Bases: Callback

Object for plotting (logging plots) inside of tensorboard. Can be passed to the pytorch lightning trainer.

Parameters:

• plot_function (callable) – A function that specfices the part of the model that should be plotted. A function that specfices the part of the model that should be plotted.

• point_sampler (torchphysics.samplers.PlotSampler) – A sampler that creates the points that should be used for the plot.

• log_interval (str, optional) – Name of the plots inside of tensorboard.

• check_interval (int, optional) – Plots will be saved every check_interval steps, if the plotter is used.

• angle (list, optional) – The view angle for surface plots. Standard angle is [30, 30]

• plot_type (str, optional) – Specifies how the output should be plotted. If no input is given, the method will try to use a fitting way, to show the data. See also plot-functions.

• kwargs – Additional arguments to specify different parameters/behaviour of the plot. See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html for possible arguments of each underlying object.

on_train_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)

Called when the train batch ends.

Note

The value outputs["loss"] here will be the normalized value w.r.t accumulate_grad_batches of the loss returned from training_step.

on_train_end(trainer, pl_module)

Called when the train ends.

on_train_start(trainer, pl_module)

Called when the train begins.

class torchphysics.utils.callbacks.TrainerStateCheckpoint(path, name, check_interval=200, weights_only=False)

Bases: Callback

A callback to save the current state of the trainer (a PyTorch Lightning checkpoint), if the training has to be resumed at a later point in time.

Parameters:

• path (str) – The relative path of the saved weights.

• name (str) – A name that will become part of the file name of the saved weights.

• check_interval (int, optional) – Checkpoints will be saved every check_interval steps. Default is 200.

• weights_only (bool, optional) – If only the model parameters should be saved. Default is false.

Note

To continue from the checkpoint, use ckpt_path=”some/path/to/my_checkpoint.ckpt” as argument in the fit command of the trainer.

The PyTorch Lightning checkpoint would save the current epoch and restart from it. In TorchPhysics we dont use multiple epochs, instead we train with multiple iterations inside “one giant epoch”. If the training is restarted, the trainer will always start from iteration 0 (essentially the last completed epoch). But all other states (model, optimizer, …) will be correctly restored.

on_train_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)

Called when the train batch ends.

Note

The value outputs["loss"] here will be the normalized value w.r.t accumulate_grad_batches of the loss returned from training_step.

class torchphysics.utils.callbacks.WeightSaveCallback(model, path, name, check_interval, save_initial_model=False, save_final_model=True)

Bases: Callback

A callback to save the weights of a model during training. Can save the model weights before, during and after training. During training, only the model with minimal loss will be saved.

Parameters:

• model (torch.nn.Module) – The model of which the weights should be saved.

• path (str) – The relative path of the saved weights.

• name (str) – A name that will become part of the file name of the saved weights.

• check_interval (int) – The callback will check for minimal loss every check_interval iterations. If negative, no weights will be saved during training.

• save_initial_model (False) – Whether the model should be saved before training as well.

• save_final_model (True) – Whether the model should always be saved after the last iteration.

on_train_batch_start(trainer, pl_module, batch, batch_idx, dataloader_idx=0)

Called when the train batch begins.

on_train_end(trainer, pl_module)

Called when the train ends.

on_train_start(trainer, pl_module)

Called when the train begins.

torchphysics.utils.differentialoperators module

File contains differentialoperators

NOTE: We aim to make the computation of differential operaotrs more efficient

by building an intelligent framework that is able to keep already computed derivatives and therefore make the computations more efficient.

torchphysics.utils.differentialoperators.convective(deriv_out, convective_field, *derivative_variable)

Computes the convective term \((v \cdot \nabla)u\) that appears e.g. in material derivatives. Note: This is not the whole material derivative.

Parameters:

• deriv_out (torch.tensor) – The vector or scalar field \(u\) that is convected and should be differentiated.

• convective_field (torch.tensor) – The flow vector field \(v\). Should have the same dimension as derivative_variable.

• derivative_variable (torch.tensor) – The spatial variable in which respect deriv_out should be differentiated.

Returns:

A vector or scalar (+batch-dimension) Tensor, that contains the convective derivative.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.div(model_out, *derivative_variable)

Computes the divergence of a network with respect to the given variable. Only for vector valued inputs, for matices use the function matrix_div. :param model_out: The output tensor of the neural network :type model_out: torch.tensor :param derivative_variable: The input tensor of the variables in which respect the derivatives have to

be computed. Have to be in a consistent ordering, if for example the output is u = (u_x, u_y) than the variables has to passed in the order (x, y)

Returns:

A Tensor, where every row contains the values of the divergence of the model w.r.t the row of the input variable.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.grad(model_out, *derivative_variable)

Computes the gradient of a network with respect to the given variable. :param model_out: The (scalar) output tensor of the neural network :type model_out: torch.tensor :param derivative_variable: The input tensor of the variables in which respect the derivatives have to

be computed

Returns:

A Tensor, where every row contains the values of the the first derivatives (gradient) w.r.t the row of the input variable.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.jac(model_out, *derivative_variable)

Computes the jacobian of a network output with respect to the given input.

Parameters:

• model_out (torch.tensor) – The output tensor in which respect the jacobian should be computed.

• derivative_variable (torch.tensor) – The input tensor in which respect the jacobian should be computed.

Returns:

A Tensor of shape (b, m, n), where every row contains a jacobian.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.laplacian(model_out, *derivative_variable, grad=None)

Computes the laplacian of a network with respect to the given variable

Parameters:

• model_out (torch.tensor) – The (scalar) output tensor of the neural network

• derivative_variable (torch.tensor) – The input tensor of the variables in which respect the derivatives have to be computed

• grad (torch.tensor) – If the gradient has already been computed somewhere else, it is more efficient to use it again.

Returns:

A Tensor, where every row contains the value of the sum of the second derivatives (laplace) w.r.t the row of the input variable.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.matrix_div(model_out, *derivative_variable)

Computes the divergence for matrix/tensor-valued functions.

Parameters:

• model_out (torch.tensor) – The (batch) of matirces that should be differentiated.

• derivative_variable (torch.tensor) – The spatial variable in which respect should be differentiated.

Returns:

A Tensor of vectors of the form (batch, dim), containing the divegrence of the input.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.normal_derivative(model_out, normals, *derivative_variable)

Computes the normal derivativ of a network with respect to the given variable and normal vectors.

Parameters:

• model_out (torch.tensor) – The (scalar) output tensor of the neural network

• derivative_variable (torch.tensor) – The input tensor of the variables in which respect the derivatives have to be computed

• normals (torch.tensor) – The normal vectors at the points where the derivative has to be computed. In the form: normals = tensor([normal_1, normal_2, …]

Returns:

A Tensor, where every row contains the values of the normal derivatives w.r.t the row of the input variable.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.partial(model_out, *derivative_variables)

Computes the (n-th, possibly mixed) partial derivative of a network output with respect to the given variables.

Parameters:

• model_out (torch.tensor) – The output tensor of the neural network

• derivative_variables (torch.tensor(s)) – The input tensors in which respect the derivatives should be computed. If n tensors are given, the n-th (mixed) derivative will be computed.

Returns:

A Tensor, where every row contains the values of the computed partial derivative of the model w.r.t the row of the input variable.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.rot(model_out, *derivative_variable)

Computes the rotation/curl of a 3-dimensional vector field (given by a network output) with respect to the given input.

Parameters:

• model_out (torch.tensor) – The output tensor of shape (b, 3) in which respect the roation should be computed.

• derivative_variable (torch.tensor) – The input tensor of shape (b, 3) in which respect the rotation should be computed.

Returns:

A Tensor of shape (b, 3), where every row contains a rotation/curl vector for a given batch element.

Return type:

torch.tensor

torchphysics.utils.differentialoperators.sym_grad(model_out, *derivative_variable)

Computes the symmetric gradient: \(0.5(\nabla u + \nabla u^T)\).

Parameters:

• model_out (torch.tensor) – The vector field \(u\) that should be differentiated.

• derivative_variable (torch.tensor) – The spatial variable in which respect model_out should be differentiated.

Returns:

A Tensor of matrices of the form (batch, dim, dim), containing the symmetric gradient.

Return type:

torch.tensor

torchphysics.utils.evaluation module

File contains different helper functions to get specific informations about the computed solution.

torchphysics.utils.evaluation.compute_min_and_max(model, sampler, evaluation_fn=<function <lambda>>, device='cpu', requieres_grad=False)

Computes the minimum and maximum values of the model w.r.t. the given variables.

Parameters:

• model (DiffEqModel) – A neural network of which values should be computed.

• sampler (torchphysics.samplers.PointSampler) – A sampler that creates the points where the model should be evaluated.

• evaluation_fn (callable) – A user-defined function that uses the neural network and creates the desiered output quantity.

• device (str or torch device) – The device of the model.

• track_gradients (bool) – Whether to track input gradients or not.

Returns:

• float – The minimum value computed.

• float – The maximum value computed.

torchphysics.utils.user_fun module

Contains a class which extracts the needed arguments of an arbitrary methode/function and wraps them for future usage. E.g correctly choosing the needed arguments and passing them on to the original function.

class torchphysics.utils.user_fun.DomainUserFunction(fun, defaults={}, args={})

Bases: UserFunction

Extension of the original UserFunctions, that are used in the Domain-Class.

Parameters:

• fun (callable) – The original function that should be wrapped.

• defaults (dict, optional) – Possible defaults arguments of the function. If none are specified will check by itself if there are any.

• args (dict, optional) – All arguments of the function. If none are specified will check by itself if there are any.

Notes

The only difference to normal UserFunction is how the evaluation of the original function is handled. Since all Domains use Pytorch, we check that the output always is a torch.tensor. In the case that the function is not constant, we also append an extra dimension to the output, so that the domains can work with it correctly.

__call__(args={}, device='cpu')

To evalute the function. Will automatically extract the needed arguments from the input data and will set the possible default values.

Parameters:

• args (dict or torchphysics.Points) – The input data, where the function should be evaluated.

• device (str, optional) – The device on which the output of th efunction values should lay. Default is ‘cpu’.

Returns:

The output values of the function.

Return type:

torch.tensor

evaluate_function(device='cpu', **inp)

Evaluates the original input function. Should not be used directly, rather use the call-methode.

Parameters:

• device (str, optional) – The device on which the output of th efunction values should lay. Default is ‘cpu’.

• inp – The input values.

class torchphysics.utils.user_fun.UserFunction(fun, defaults={}, args={})

Bases: object

Wraps a function, so that it can be called with arbitrary input arguments.

Parameters:

• fun (callable) – The original function that should be wrapped.

• defaults (dict, optional) – Possible defaults arguments of the function. If none are specified will check by itself if there are any.

• args (dict, optional) – All arguments of the function. If none are specified will check by itself if there are any.

Notes

Uses inspect.getfullargspec(fun) to get the possible input arguments. When called just extracts the needed arguments and passes them to the original function.

__call__(args={}, vectorize=False)

To evalute the function. Will automatically extract the needed arguments from the input data and will set the possible default values.

Parameters:

• args (dict or torchphysics.Points) – The input data, where the function should be evaluated.

• vectorize (bool, optional) – If the original function can work with a batch of data, or a loop needs to be used to evaluate the function. default is False, which means that we assume the function can work with a batch of data.

Returns:

The output values of the function.

Return type:

torch.tensor

apply_to_batch(inp)

Apply the function to a batch of elements by running a for-loop. we assume that all inputs either have batch (i.e. maximum) dimension or are a constant param.

Parameters:

inp (torchphysics.points) – The Points-object of the input data

Returns:

The output values of the function, for each input.

Return type:

torch.tensor

evaluate_function(**inp)

Evaluates the original input function. Should not be used directly, rather use the call-methode.

property necessary_args

Returns the function arguments that are needed to evaluate this function.

Returns:

The needed arguments.

Return type:

list

property optional_args

Returns the function arguments that are optional to evaluate this function.

Returns:

The optional arguments.

Return type:

list

partially_evaluate(**args)

(partially) evaluates a given function.

Parameters:

**args – The arguments where the function should be (partially) evaluated.

Returns:

Out – If the input arguments are enough to evalate the whole function, the corresponding output is returned. If some needed arguments are missing, a copy of this UserFunction will be returned. Whereby the values of **args will be added to the default values of the returned UserFunction.

Return type:

value or UserFunction

remove_default(*args, **kwargs)

Removes an default value of a input argument.

Parameters:

• *args – The arguments for which the default values should be deleted.

• **kwargs – The arguments for which the default values should be deleted.

set_default(**args)

Sets a input argument to given value.

Parameters:

**args – The value the input should be set to.