From da33aeae3a4dfb80a99a961283abefb9be3911db Mon Sep 17 00:00:00 2001 From: Anna Ivagnes <75523024+annaivagnes@users.noreply.github.com> Date: Tue, 18 Apr 2023 10:49:01 +0200 Subject: [PATCH] partially fix documentation (#80) --- docs/source/_rst/abstractproblem.rst | 12 +++++++ docs/source/_rst/code.rst | 6 +++- docs/source/_rst/multifeedforward.rst | 12 +++++++ docs/source/_rst/parametricproblem.rst | 12 +++++++ docs/source/_rst/spatialproblem.rst | 12 +++++++ docs/source/_rst/timedepproblem.rst | 12 +++++++ pina/model/multi_feed_forward.py | 9 +++-- pina/problem/abstract_problem.py | 28 +++++++++++++++ pina/problem/parametric_problem.py | 36 +++++++++++++++++++ pina/problem/spatial_problem.py | 39 +++++++++++++++++++++ pina/problem/timedep_problem.py | 48 ++++++++++++++++++++++++++ 11 files changed, 222 insertions(+), 4 deletions(-) create mode 100644 docs/source/_rst/abstractproblem.rst create mode 100644 docs/source/_rst/multifeedforward.rst create mode 100644 docs/source/_rst/parametricproblem.rst create mode 100644 docs/source/_rst/spatialproblem.rst create mode 100644 docs/source/_rst/timedepproblem.rst diff --git a/docs/source/_rst/abstractproblem.rst b/docs/source/_rst/abstractproblem.rst new file mode 100644 index 0000000..f6a0873 --- /dev/null +++ b/docs/source/_rst/abstractproblem.rst @@ -0,0 +1,12 @@ +AbstractProblem +=========== +.. currentmodule:: pina.problem.abstract_problem + +.. automodule:: pina.problem.abstract_problem + +.. autoclass:: AbstractProblem + :members: + :private-members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/docs/source/_rst/code.rst b/docs/source/_rst/code.rst index 6a0601e..a74dc26 100644 --- a/docs/source/_rst/code.rst +++ b/docs/source/_rst/code.rst @@ -10,5 +10,9 @@ Code Documentation FeedForward DeepONet ContinuousConv + MultiFeedForward + AbstractProblem + SpatialProblem + TimeDependentProblem Operators - Plotter + Plotter \ No newline at end of file diff --git a/docs/source/_rst/multifeedforward.rst b/docs/source/_rst/multifeedforward.rst new file mode 100644 index 0000000..30a3e06 --- /dev/null +++ b/docs/source/_rst/multifeedforward.rst @@ -0,0 +1,12 @@ +MultiFeedForward +=========== +.. currentmodule:: pina.model.multi_feed_forward + +.. automodule:: pina.model.multi_feed_forward + +.. autoclass:: MultiFeedForward + :members: + :private-members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/docs/source/_rst/parametricproblem.rst b/docs/source/_rst/parametricproblem.rst new file mode 100644 index 0000000..bd8dab8 --- /dev/null +++ b/docs/source/_rst/parametricproblem.rst @@ -0,0 +1,12 @@ +ParametricProblem +=========== +.. currentmodule:: pina.problem.parametric_problem + +.. automodule:: pina.problem.parametric_problem + +.. autoclass:: ParametricProblem + :members: + :private-members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/docs/source/_rst/spatialproblem.rst b/docs/source/_rst/spatialproblem.rst new file mode 100644 index 0000000..896892f --- /dev/null +++ b/docs/source/_rst/spatialproblem.rst @@ -0,0 +1,12 @@ +SpatialProblem +=========== +.. currentmodule:: pina.problem.spatial_problem + +.. automodule:: pina.problem.spatial_problem + +.. autoclass:: SpatialProblem + :members: + :private-members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/docs/source/_rst/timedepproblem.rst b/docs/source/_rst/timedepproblem.rst new file mode 100644 index 0000000..e96c344 --- /dev/null +++ b/docs/source/_rst/timedepproblem.rst @@ -0,0 +1,12 @@ +TimeDependentProblem +=========== +.. currentmodule:: pina.problem.timedep_problem + +.. automodule:: pina.problem.timedep_problem + +.. autoclass:: TimeDependentProblem + :members: + :private-members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/pina/model/multi_feed_forward.py b/pina/model/multi_feed_forward.py index b5de7e7..984647e 100644 --- a/pina/model/multi_feed_forward.py +++ b/pina/model/multi_feed_forward.py @@ -1,13 +1,16 @@ +"""Module for Multi FeedForward model""" import torch from .feed_forward import FeedForward class MultiFeedForward(torch.nn.Module): - + """ + :param dict dff_dict: dictionary of FeedForward networks. + """ def __init__(self, dff_dict): - ''' - ''' + """ + """ super().__init__() if not isinstance(dff_dict, dict): diff --git a/pina/problem/abstract_problem.py b/pina/problem/abstract_problem.py index d1abe5c..fc81e22 100644 --- a/pina/problem/abstract_problem.py +++ b/pina/problem/abstract_problem.py @@ -1,10 +1,26 @@ +""" Module for AbstractProblem class """ from abc import ABCMeta, abstractmethod class AbstractProblem(metaclass=ABCMeta): + """ + The abstract `AbstractProblem` class. All the class defining a PINA Problem + should be inheritied from this class. + In the definition of a PINA problem, the fundamental elements are: + the output variables, the condition(s), and the domain(s) where the + conditions are applied. + """ @property def input_variables(self): + """ + The input variables of the AbstractProblem, whose type depends on the + type of domain (spatial, temporal, and parameter). + + :return: the input variables of self + :rtype: list + + """ variables = [] if hasattr(self, 'spatial_variables'): @@ -20,7 +36,13 @@ class AbstractProblem(metaclass=ABCMeta): @property def domain(self): + """ + The domain(s) where the conditions of the AbstractProblem are valid. + :return: the domain(s) of self + :rtype: list (if more than one domain are defined), + `Span` domain (of only one domain is defined) + """ domains = [ getattr(self, f'{t}_domain') for t in ['spatial', 'temporal', 'parameter'] @@ -46,9 +68,15 @@ class AbstractProblem(metaclass=ABCMeta): @property @abstractmethod def output_variables(self): + """ + The output variables of the problem. + """ pass @property @abstractmethod def conditions(self): + """ + The conditions of the problem. + """ pass diff --git a/pina/problem/parametric_problem.py b/pina/problem/parametric_problem.py index bc11fdb..430ee32 100644 --- a/pina/problem/parametric_problem.py +++ b/pina/problem/parametric_problem.py @@ -1,9 +1,45 @@ +"""Module for the ParametricProblem class""" from abc import abstractmethod from .abstract_problem import AbstractProblem class ParametricProblem(AbstractProblem): + """ + The class for the definition of parametric problems, i.e., problems + with parameters among the input variables. + + Here's an example of a spatial parametric ODE problem, i.e., a spatial + ODE problem with an additional parameter `alpha` as coefficient of the + derivative term. + + :Example: + >>> from pina.problem import SpatialProblem, ParametricProblem + >>> from pina.operators import grad + >>> from pina import Condition, Span + >>> import torch + + >>> class ParametricODE(SpatialProblem, ParametricProblem): + + >>> output_variables = ['u'] + >>> spatial_domain = Span({'x': [0, 1]}) + >>> parameter_domain = Span({'alpha': {1, 10}}) + + >>> def ode_equation(input_, output_): + >>> u_x = grad(output_, input_, components=['u'], d=['x']) + >>> u = output_.extract(['u']) + >>> alpha = input_.extract(['alpha']) + >>> return alpha * u_x - u + + >>> def initial_condition(input_, output_): + >>> value = 1.0 + >>> u = output_.extract(['u']) + >>> return u - value + + >>> conditions = { + >>> 'x0': Condition(Span({'x': 0, 'alpha':[1, 10]}), initial_condition), + >>> 'D': Condition(Span({'x': [0, 1], 'alpha':[1, 10]}), ode_equation)} + """ @abstractmethod def parameter_domain(self): diff --git a/pina/problem/spatial_problem.py b/pina/problem/spatial_problem.py index 3d236a1..be3d607 100644 --- a/pina/problem/spatial_problem.py +++ b/pina/problem/spatial_problem.py @@ -1,14 +1,53 @@ +"""Module for the SpatialProblem class""" from abc import abstractmethod from .abstract_problem import AbstractProblem class SpatialProblem(AbstractProblem): + """ + The class for the definition of spatial problems, i.e., for problems + with spatial input variables. + + Here's an example of a spatial 1-dimensional ODE problem. + + :Example: + >>> from pina.problem import SpatialProblem + >>> from pina.operators import grad + >>> from pina import Condition, Span + >>> import torch + + >>> class SimpleODE(SpatialProblem): + + >>> output_variables = ['u'] + >>> spatial_domain = Span({'x': [0, 1]}) + + >>> def ode_equation(input_, output_): + >>> u_x = grad(output_, input_, components=['u'], d=['x']) + >>> u = output_.extract(['u']) + >>> return u_x - u + + >>> def initial_condition(input_, output_): + >>> value = 1.0 + >>> u = output_.extract(['u']) + >>> return u - value + + >>> conditions = { + >>> 'x0': Condition(Span({'x': 0.}), initial_condition), + >>> 'D': Condition(Span({'x': [0, 1]}), ode_equation)} + + """ @abstractmethod def spatial_domain(self): + """ + The spatial domain of the problem. + """ pass @property def spatial_variables(self): + """ + The spatial input variables of the problem. + """ return self.spatial_domain.variables diff --git a/pina/problem/timedep_problem.py b/pina/problem/timedep_problem.py index 759afd1..8870204 100644 --- a/pina/problem/timedep_problem.py +++ b/pina/problem/timedep_problem.py @@ -1,14 +1,62 @@ +"""Module for the TimeDependentProblem class""" from abc import abstractmethod from .abstract_problem import AbstractProblem class TimeDependentProblem(AbstractProblem): + """ + The class for the definition of time-dependent problems, i.e., for problems + depending on time. + + Here's an example of a 1D wave problem. + + :Example: + >>> from pina.problem import SpatialProblem, TimeDependentProblem + >>> from pina.operators import grad, nabla + >>> from pina import Condition, Span + >>> import torch + + >>> class Wave(TimeDependentSpatialProblem): + + >>> output_variables = ['u'] + >>> spatial_domain = Span({'x': [0, 3]}) + >>> temporal_domain = Span({'t': [0, 1]}) + + >>> def wave_equation(input_, output_): + >>> u_t = grad(output_, input_, components=['u'], d=['t']) + >>> u_tt = grad(u_t, input_, components=['dudt'], d=['t']) + >>> nabla_u = nabla(output_, input_, components=['u'], d=['x']) + >>> return nabla_u - u_tt + + >>> def nil_dirichlet(input_, output_): + >>> value = 0.0 + >>> return output_.extract(['u']) - value + + >>> def initial_condition(input_, output_): + >>> u_expected = (-3*torch.sin(2*torch.pi*input_.extract(['x'])) + >>> + 5*torch.sin(8/3*torch.pi*input_.extract(['x']))) + >>> u = output_.extract(['u']) + >>> return u - u_expected + + >>> conditions = { + >>> 't0': Condition(Span({'x': [0, 3], 't':0}), initial_condition), + >>> 'gamma1': Condition(Span({'x':0, 't':[0, 1]}), nil_dirichlet), + >>> 'gamma2': Condition(Span({'x':3, 't':[0, 1]}), nil_dirichlet), + >>> 'D': Condition(Span({'x': [0, 3], 't':[0, 1]}), wave_equation)} + + """ @abstractmethod def temporal_domain(self): + """ + The temporal domain of the problem. + """ pass @property def temporal_variable(self): + """ + The time variable of the problem. + """ return self.temporal_domain.variables