From e0ad4dc8a02e6f478ebed02ae56624290fefd7d6 Mon Sep 17 00:00:00 2001 From: giovanni Date: Thu, 13 Mar 2025 22:31:26 +0100 Subject: [PATCH] fix rendering part 1 --- pina/domain/difference_domain.py | 10 +++++----- pina/domain/ellipsoid.py | 16 ++++++++-------- pina/domain/exclusion_domain.py | 4 ++-- pina/domain/intersection_domain.py | 4 ++-- pina/domain/operation_interface.py | 4 ++-- pina/domain/union_domain.py | 4 ++-- pina/equation/equation.py | 12 +++++++----- pina/equation/equation_factory.py | 8 ++++---- pina/equation/equation_interface.py | 16 ++++++++++++++-- pina/equation/system_equation.py | 12 +++++++----- pina/optim/torch_optimizer.py | 4 ++-- pina/optim/torch_scheduler.py | 4 ++-- pina/problem/abstract_problem.py | 14 +++++++++----- pina/trainer.py | 21 +++++++++++++-------- pina/utils.py | 19 ++++++++++--------- 15 files changed, 89 insertions(+), 63 deletions(-) diff --git a/pina/domain/difference_domain.py b/pina/domain/difference_domain.py index a2d74cf..4ea7b52 100644 --- a/pina/domain/difference_domain.py +++ b/pina/domain/difference_domain.py @@ -23,11 +23,11 @@ class Difference(OperationInterface): Initialization of the :class:`Difference` class. :param list[DomainInterface] geometries: A list of instances of the - :class:`~pina.domain.DomainInterface` class on which the difference - operation is performed. The first domain in the list serves as the - base from which points are sampled, while the remaining domains - define the regions to be excluded from the base domain to compute - the difference. + :class:`~pina.domain.domain_interface.DomainInterface` class on + which the difference operation is performed. The first domain in the + list serves as the base from which points are sampled, while the + remaining domains define the regions to be excluded from the base + domain to compute the difference. :Example: >>> # Create two ellipsoid domains diff --git a/pina/domain/ellipsoid.py b/pina/domain/ellipsoid.py index b828be7..5411e46 100644 --- a/pina/domain/ellipsoid.py +++ b/pina/domain/ellipsoid.py @@ -26,14 +26,14 @@ class EllipsoidDomain(DomainInterface): .. warning:: Sampling for dimensions greater or equal to 10 could result in a shrinkage of the ellipsoid, which degrades the quality of the - samples. For dimensions higher than 10, use other sampling - algorithms. - .. seealso:: - **Original reference**: Dezert, Jean, and Musso, Christian. - *An efficient method for generating points uniformly distributed - in hyperellipsoids.* - Proceedings of the Workshop on Estimation, Tracking and Fusion: - A Tribute to Yaakov Bar-Shalom. 2001. + samples. For dimensions higher than 10, see the following reference. + + .. seealso:: + **Original reference**: Dezert, Jean, and Musso, Christian. + *An efficient method for generating points uniformly distributed + in hyperellipsoids.* + Proceedings of the Workshop on Estimation, Tracking and Fusion: + A Tribute to Yaakov Bar-Shalom. 2001. :Example: >>> spatial_domain = Ellipsoid({'x':[-1, 1], 'y':[-1,1]}) diff --git a/pina/domain/exclusion_domain.py b/pina/domain/exclusion_domain.py index db9564b..4a61e41 100644 --- a/pina/domain/exclusion_domain.py +++ b/pina/domain/exclusion_domain.py @@ -25,8 +25,8 @@ class Exclusion(OperationInterface): Initialization of the :class:`Exclusion` class. :param list[DomainInterface] geometries: A list of instances of the - :class:`~pina.domain.DomainInterface` class on which the exclusion - operation is performed. + :class:`~pina.domain.domain_interface.DomainInterface` class on + which the exclusion operation is performed. :Example: >>> # Create two ellipsoid domains diff --git a/pina/domain/intersection_domain.py b/pina/domain/intersection_domain.py index c6ffe8f..0921ff3 100644 --- a/pina/domain/intersection_domain.py +++ b/pina/domain/intersection_domain.py @@ -24,8 +24,8 @@ class Intersection(OperationInterface): Initialization of the :class:`Intersection` class. :param list[DomainInterface] geometries: A list of instances of the - :class:`~pina.domain.DomainInterface` class on which the - intersection operation is performed. + :class:`~pina.domain.domain_interface.DomainInterface` class on + which the intersection operation is performed. :Example: >>> # Create two ellipsoid domains diff --git a/pina/domain/operation_interface.py b/pina/domain/operation_interface.py index b377c41..8cce969 100644 --- a/pina/domain/operation_interface.py +++ b/pina/domain/operation_interface.py @@ -15,8 +15,8 @@ class OperationInterface(DomainInterface, metaclass=ABCMeta): Initialization of the :class:`OperationInterface` class. :param list[DomainInterface] geometries: A list of instances of the - :class:`~pina.domain.DomainInterface` class on which the set - operation is performed. + :class:`~pina.domain.domain_interface.DomainInterface` class on + which the set operation is performed. """ # check consistency geometries check_consistency(geometries, DomainInterface) diff --git a/pina/domain/union_domain.py b/pina/domain/union_domain.py index f3f3b4f..5c3e96f 100644 --- a/pina/domain/union_domain.py +++ b/pina/domain/union_domain.py @@ -23,8 +23,8 @@ class Union(OperationInterface): Initialization of the :class:`Union` class. :param list[DomainInterface] geometries: A list of instances of the - :class:`~pina.domain.DomainInterface` class on which the union - operation is performed. + :class:`~pina.domain.domain_interface.DomainInterface` class on + which the union operation is performed. :Example: >>> # Create two ellipsoid domains diff --git a/pina/equation/equation.py b/pina/equation/equation.py index 34a4703..fef4642 100644 --- a/pina/equation/equation.py +++ b/pina/equation/equation.py @@ -6,8 +6,9 @@ from .equation_interface import EquationInterface class Equation(EquationInterface): """ Implementation of the Equation class. Every ``equation`` passed to a - :class:`~pina.condition.Condition` object must be either a :class:`Equation` - or a :class:`~pina.equation.SystemEquation` instance. + :class:`~pina.condition.condition.Condition` object must be either an + instance of :class:`Equation` or + :class:`~pina.equation.system_equation.SystemEquation`. """ def __init__(self, equation): @@ -32,10 +33,11 @@ class Equation(EquationInterface): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :param dict params_: Dictionary of unknown parameters, associated with a - :class:`~pina.problem.InverseProblem` instance. If the equation is - not related to a :class:`~pina.problem.InverseProblem` instance, the + :class:`~pina.problem.inverse_problem.InverseProblem` instance. + If the equation is not related to a + :class:`~pina.problem.inverse_problem.InverseProblem` instance, the parameters must be initialized to ``None``. Default is ``None``. :return: The computed residual of the equation. :rtype: LabelTensor diff --git a/pina/equation/equation_factory.py b/pina/equation/equation_factory.py index 14862ee..879990a 100644 --- a/pina/equation/equation_factory.py +++ b/pina/equation/equation_factory.py @@ -28,7 +28,7 @@ class FixedValue(Equation): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :return: The computed residual of the equation. :rtype: LabelTensor """ @@ -66,7 +66,7 @@ class FixedGradient(Equation): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :return: The computed residual of the equation. :rtype: LabelTensor """ @@ -101,7 +101,7 @@ class FixedFlux(Equation): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :return: The computed residual of the equation. :rtype: LabelTensor """ @@ -136,7 +136,7 @@ class Laplace(Equation): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :return: The computed residual of the equation. :rtype: LabelTensor """ diff --git a/pina/equation/equation_interface.py b/pina/equation/equation_interface.py index 8941d1e..66b210c 100644 --- a/pina/equation/equation_interface.py +++ b/pina/equation/equation_interface.py @@ -6,6 +6,18 @@ from abc import ABCMeta, abstractmethod class EquationInterface(metaclass=ABCMeta): """ Abstract base class for equations. + + Equations in PINA simplify the training process. When defining a problem, + each equation passed to a :class:`~pina.condition.condition.Condition` + object must be either an :class:`~pina.equation.equation.Equation` or a + :class:`~pina.equation.system_equation.SystemEquation` instance. + + An :class:`~pina.equation.equation.Equation` is a wrapper for a callable + function, while :class:`~pina.equation.system_equation.SystemEquation` + wraps a list of callable functions. To streamline code writing, PINA + provides a diverse set of pre-implemented equations, such as + :class:`~pina.equation.equation_factory.FixedValue`, + :class:`~pina.equation.equation_factory.FixedGradient`, and many others. """ @abstractmethod @@ -15,9 +27,9 @@ class EquationInterface(metaclass=ABCMeta): :param LabelTensor input_: Input points where the equation is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :param dict params_: Dictionary of unknown parameters, associated with a - :class:`~pina.problem.InverseProblem` instance. + :class:`~pina.problem.inverse_problem.InverseProblem` instance. :return: The computed residual of the equation. :rtype: LabelTensor """ diff --git a/pina/equation/system_equation.py b/pina/equation/system_equation.py index ff4cf61..d51ba94 100644 --- a/pina/equation/system_equation.py +++ b/pina/equation/system_equation.py @@ -9,8 +9,9 @@ from ..utils import check_consistency class SystemEquation(EquationInterface): """ Implementation of the System of Equations. Every ``equation`` passed to a - :class:`~pina.condition.Condition` object must be either a :class:`Equation` - or a :class:`~pina.equation.SystemEquation` instance. + :class:`~pina.condition.condition.Condition` object must be either a + :class:`~pina.equation.equation.Equation` or a + :class:`~pina.equation.system_equation.SystemEquation` instance. """ def __init__(self, list_equation, reduction=None): @@ -56,10 +57,11 @@ class SystemEquation(EquationInterface): :param LabelTensor input_: Input points where each equation of the system is evaluated. :param LabelTensor output_: Output tensor, eventually produced by a - :class:`~torch.nn.Module` instance. + :class:`torch.nn.Module` instance. :param dict params_: Dictionary of unknown parameters, associated with a - :class:`~pina.problem.InverseProblem` instance. If the equation is - not related to a :class:`~pina.problem.InverseProblem` instance, the + :class:`~pina.problem.inverse_problem.InverseProblem` instance. + If the equation is not related to a + :class:`~pina.problem.inverse_problem.InverseProblem` instance, the parameters must be initialized to ``None``. Default is ``None``. :return: The aggregated residuals of the system of equations. diff --git a/pina/optim/torch_optimizer.py b/pina/optim/torch_optimizer.py index fc34296..9c8674c 100644 --- a/pina/optim/torch_optimizer.py +++ b/pina/optim/torch_optimizer.py @@ -15,8 +15,8 @@ class TorchOptimizer(Optimizer): """ Initialization of the :class:`TorchOptimizer` class. - :param torch.optim.Optimizer optimizer_class: The PyTorch optimizer - class. + :param torch.optim.Optimizer optimizer_class: A + :class:`torch.optim.Optimizer` class. :param dict kwargs: Additional parameters passed to `optimizer_class`, see more: _. """ diff --git a/pina/optim/torch_scheduler.py b/pina/optim/torch_scheduler.py index c436e22..40b5e46 100644 --- a/pina/optim/torch_scheduler.py +++ b/pina/optim/torch_scheduler.py @@ -21,8 +21,8 @@ class TorchScheduler(Scheduler): """ Initialization of the :class:`TorchScheduler` class. - :param torch.optim.LRScheduler scheduler_class: The PyTorch scheduler - class. + :param torch.optim.LRScheduler scheduler_class: A + :class:`torch.optim.LRScheduler` class. :param dict kwargs: Additional parameters passed to `scheduler_class`, see more: _. """ diff --git a/pina/problem/abstract_problem.py b/pina/problem/abstract_problem.py index 27207ae..d177239 100644 --- a/pina/problem/abstract_problem.py +++ b/pina/problem/abstract_problem.py @@ -188,11 +188,15 @@ class AbstractProblem(metaclass=ABCMeta): .. warning:: ``random`` is currently the only implemented ``mode`` for all - geometries, i.e. ``EllipsoidDomain``, ``CartesianDomain``, - ``SimplexDomain``, and geometry compositions ``Union``, - ``Difference``, ``Exclusion``, ``Intersection``. The - modes ``latin`` or ``lh``, ``chebyshev``, ``grid`` are only - implemented for ``CartesianDomain``. + geometries, i.e. :class:`~pina.domain.ellipsoid.EllipsoidDomain`, + :class:`~pina.domain.cartesian.CartesianDomain`, + :class:`~pina.domain.simplex.SimplexDomain`, and geometry + compositions :class:`~pina.domain.union_domain.Union`, + :class:`~pina.domain.difference_domain.Difference`, + :class:`~pina.domain.exclusion_domain.Exclusion`, and + :class:`~pina.domain.intersection_domain.Intersection`. + The modes ``latin`` or ``lh``, ``chebyshev``, ``grid`` are only + implemented for :class:`~pina.domain.cartesian.CartesianDomain`. """ # check consistecy n, mode, variables, locations diff --git a/pina/trainer.py b/pina/trainer.py index 37c1c06..0d82bdd 100644 --- a/pina/trainer.py +++ b/pina/trainer.py @@ -34,8 +34,9 @@ class Trainer(lightning.pytorch.Trainer): """ Initialization of the :class:`Trainer` class. - :param SolverInterface solver: A :class:`~pina.solver.SolverInterface` - solver used to solve a :class:`~pina.problem.AbstractProblem`. + :param SolverInterface solver: A + :class:`~pina.solver.solver.SolverInterface` solver used to solve a + :class:`~pina.problem.abstract_problem.AbstractProblem`. :param int batch_size: The number of samples per batch to load. If ``None``, all samples are loaded and data is not batched. Default is ``None``. @@ -56,11 +57,10 @@ class Trainer(lightning.pytorch.Trainer): transfer to GPU. Default is ``False``. :param bool shuffle: Whether to shuffle the data during training. Default is ``True``. - - :Keyword Arguments: - Additional keyword arguments that specify the training setup. - These can be selected from the pytorch-lightning Trainer API - _. + :param dict kwargs: Additional keyword arguments that specify the + training setup. These can be selected from the `pytorch-lightning + Trainer API + `_. """ # check consistency for init types self._check_input_consistency( @@ -132,7 +132,8 @@ class Trainer(lightning.pytorch.Trainer): def _move_to_device(self): """ Moves the ``unknown_parameters`` of an instance of - :class:`~pina.problem.AbstractProblem` to the :class:`Trainer` device. + :class:`~pina.problem.abstract_problem.AbstractProblem` to the + :class:`Trainer` device. """ device = self._accelerator_connector._parallel_devices[0] # move parameters to device @@ -205,12 +206,16 @@ class Trainer(lightning.pytorch.Trainer): def train(self, **kwargs): """ Manage the training process of the solver. + + :param dict kwargs: Additional keyword arguments. """ return super().fit(self.solver, datamodule=self.data_module, **kwargs) def test(self, **kwargs): """ Manage the test process of the solver. + + :param dict kwargs: Additional keyword arguments. """ return super().test(self.solver, datamodule=self.data_module, **kwargs) diff --git a/pina/utils.py b/pina/utils.py index 123e3e4..56b329b 100644 --- a/pina/utils.py +++ b/pina/utils.py @@ -60,14 +60,14 @@ def check_consistency(object_, object_instance, subclass=False): def labelize_forward(forward, input_variables, output_variables): """ - Decorator to enable or disable the use of :class:`~pina.LabelTensor` - during the forward pass. + Decorator to enable or disable the use of + :class:`~pina.label_tensor.LabelTensor` during the forward pass. :param Callable forward: The forward function of a :class:`torch.nn.Module`. :param list[str] input_variables: The names of the input variables of a - :class:`~pina.problem.AbstractProblem`. + :class:`~pina.problem.abstract_problem.AbstractProblem`. :param list[str] output_variables: The names of the output variables of a - :class:`~pina.problem.AbstractProblem`. + :class:`~pina.problem.abstract_problem.AbstractProblem`. :return: The decorated forward function. :rtype: Callable """ @@ -95,9 +95,9 @@ def labelize_forward(forward, input_variables, output_variables): def merge_tensors(tensors): """ - Merge a list of :class:`~pina.LabelTensor` instances into a single - :class:`~pina.LabelTensor` tensor, by applying iteratively the cartesian - product. + Merge a list of :class:`~pina.label_tensor.LabelTensor` instances into a + single :class:`~pina.label_tensor.LabelTensor` tensor, by applying + iteratively the cartesian product. :param list[LabelTensor] tensors: The list of tensors to merge. :raises ValueError: If the list of tensors is empty. @@ -111,8 +111,9 @@ def merge_tensors(tensors): def merge_two_tensors(tensor1, tensor2): """ - Merge two :class:`~pina.LabelTensor` instances into a single - :class:`~pina.LabelTensor` tensor, by applying the cartesian product. + Merge two :class:`~pina.label_tensor.LabelTensor` instances into a single + :class:`~pina.label_tensor.LabelTensor` tensor, by applying the cartesian + product. :param LabelTensor tensor1: The first tensor to merge. :param LabelTensor tensor2: The second tensor to merge.