From ebce306daddb08eff9e2aef88c5b3b161c3f078a Mon Sep 17 00:00:00 2001 From: Sichao He <1310722434@qq.com> Date: Fri, 13 Dec 2024 23:58:53 +0800 Subject: [PATCH 1/2] [docs] Add auto API generator --- .gitignore | 3 +- docs/_templates/classtemplate.rst | 9 + docs/apis/pinnx.callbacks.rst | 26 +++ docs/apis/pinnx.fnspace.rst | 23 ++ docs/apis/pinnx.geometry.rst | 117 ++++++++++ docs/apis/pinnx.grad.rst | 19 ++ docs/apis/pinnx.icbc.rst | 50 ++++ docs/apis/pinnx.metrics.rst | 24 ++ docs/apis/pinnx.nn.rst | 108 +++++++++ docs/apis/pinnx.problem.rst | 122 ++++++++++ docs/apis/pinnx.rst | 17 ++ docs/apis/pinnx.utils.rst | 156 +++++++++++++ docs/auto_generater.py | 370 ++++++++++++++++++++++++++++++ docs/conf.py | 5 + docs/index.rst | 15 ++ pinnx/metrics.py | 9 +- pinnx/nn/output.py | 24 -- 17 files changed, 1070 insertions(+), 27 deletions(-) create mode 100644 docs/_templates/classtemplate.rst create mode 100644 docs/apis/pinnx.callbacks.rst create mode 100644 docs/apis/pinnx.fnspace.rst create mode 100644 docs/apis/pinnx.geometry.rst create mode 100644 docs/apis/pinnx.grad.rst create mode 100644 docs/apis/pinnx.icbc.rst create mode 100644 docs/apis/pinnx.metrics.rst create mode 100644 docs/apis/pinnx.nn.rst create mode 100644 docs/apis/pinnx.problem.rst create mode 100644 docs/apis/pinnx.rst create mode 100644 docs/apis/pinnx.utils.rst create mode 100644 docs/auto_generater.py delete mode 100644 pinnx/nn/output.py diff --git a/.gitignore b/.gitignore index 2efd78b..67c371b 100644 --- a/.gitignore +++ b/.gitignore @@ -30,4 +30,5 @@ related-projects.md docs/**/*.dat docs/**/*.npz -.DS_Store \ No newline at end of file +.DS_Store +docs/apis/generated/ \ No newline at end of file diff --git a/docs/_templates/classtemplate.rst b/docs/_templates/classtemplate.rst new file mode 100644 index 0000000..e783a6c --- /dev/null +++ b/docs/_templates/classtemplate.rst @@ -0,0 +1,9 @@ +.. role:: hidden + :class: hidden-section +.. currentmodule:: {{ module }} + + +{{ name | underline}} + +.. autoclass:: {{ name }} + :members: \ No newline at end of file diff --git a/docs/apis/pinnx.callbacks.rst b/docs/apis/pinnx.callbacks.rst new file mode 100644 index 0000000..e803538 --- /dev/null +++ b/docs/apis/pinnx.callbacks.rst @@ -0,0 +1,26 @@ +``pinnx.callbacks`` module +========================== + +.. currentmodule:: pinnx.callbacks +.. automodule:: pinnx.callbacks + +Callbacks +--------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Callback + CallbackList + ModelCheckpoint + EarlyStopping + Timer + DropoutUncertainty + VariableValue + OperatorPredictor + MovieDumper + PDEPointResampler + + diff --git a/docs/apis/pinnx.fnspace.rst b/docs/apis/pinnx.fnspace.rst new file mode 100644 index 0000000..4cfa92b --- /dev/null +++ b/docs/apis/pinnx.fnspace.rst @@ -0,0 +1,23 @@ +``pinnx.fnspace`` module +======================== + +.. currentmodule:: pinnx.fnspace +.. automodule:: pinnx.fnspace + +Function Space +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + wasserstein2 + FunctionSpace + PowerSeries + Chebyshev + GRF + GRF_KL + GRF2D + + diff --git a/docs/apis/pinnx.geometry.rst b/docs/apis/pinnx.geometry.rst new file mode 100644 index 0000000..ab22761 --- /dev/null +++ b/docs/apis/pinnx.geometry.rst @@ -0,0 +1,117 @@ +``pinnx.geometry`` module +========================= + +.. currentmodule:: pinnx.geometry +.. automodule:: pinnx.geometry + +Base Geometry Class +------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + AbstractGeometry + Geometry + CSGUnion + CSGDifference + CSGIntersection + + +Geometry in 1D +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + sample + Geometry + Interval + Literal + Union + + +Geometry in 2D +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Disk + Ellipse + Polygon + Rectangle + StarShaped + Triangle + + +Geometry in 3D +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Rectangle + Hypercube + Hypersphere + Cuboid + Sphere + Union + Literal + + +Geometry in ND +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + sample + isclose + Geometry + Hypercube + Hypersphere + Literal + + +Point Cloud +----------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + isclose + BatchSampler + Geometry + PointCloud + + +Time Domain +----------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + isclose + AbstractGeometry + Interval + Rectangle + Cuboid + Hypercube + TimeDomain + GeometryXTime + + diff --git a/docs/apis/pinnx.grad.rst b/docs/apis/pinnx.grad.rst new file mode 100644 index 0000000..69fd4a7 --- /dev/null +++ b/docs/apis/pinnx.grad.rst @@ -0,0 +1,19 @@ +``pinnx.grad`` module +===================== + +.. currentmodule:: pinnx.grad +.. automodule:: pinnx.grad + +Automatic Differentiation +------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + jacobian + hessian + gradient + + diff --git a/docs/apis/pinnx.icbc.rst b/docs/apis/pinnx.icbc.rst new file mode 100644 index 0000000..cccaeb7 --- /dev/null +++ b/docs/apis/pinnx.icbc.rst @@ -0,0 +1,50 @@ +``pinnx.icbc`` module +===================== + +.. currentmodule:: pinnx.icbc +.. automodule:: pinnx.icbc + +Base Initial and Boundary Conditions Class +------------------------------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + AbstractGeometry + ICBC + Optional + Dict + + +Boundary Conditions +------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + BC + DirichletBC + Interface2DBC + NeumannBC + OperatorBC + PeriodicBC + PointSetBC + PointSetOperatorBC + RobinBC + + +Initial Conditions +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + IC + + diff --git a/docs/apis/pinnx.metrics.rst b/docs/apis/pinnx.metrics.rst new file mode 100644 index 0000000..abc04b3 --- /dev/null +++ b/docs/apis/pinnx.metrics.rst @@ -0,0 +1,24 @@ +``pinnx.metrics`` module +======================== + +.. currentmodule:: pinnx.metrics +.. automodule:: pinnx.metrics + +Metrics +------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + accuracy + l2_relative_error + nanl2_relative_error + mean_l2_relative_error + mean_squared_error + mean_absolute_percentage_error + max_absolute_percentage_error + absolute_percentage_error_std + + diff --git a/docs/apis/pinnx.nn.rst b/docs/apis/pinnx.nn.rst new file mode 100644 index 0000000..5ca4487 --- /dev/null +++ b/docs/apis/pinnx.nn.rst @@ -0,0 +1,108 @@ +``pinnx.nn`` module +=================== + +.. currentmodule:: pinnx.nn +.. automodule:: pinnx.nn + +Base Neural Network Class +------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + NN + Optional + Callable + + +Dict and Array Converters +------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + DictToArray + ArrayToDict + + +DeepONet Strategy +----------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + abstractmethod + ABC + DeepONetStrategy + SingleOutputStrategy + IndependentStrategy + SplitBothStrategy + SplitBranchStrategy + SplitTrunkStrategy + + +DeepONet +-------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + DeepONet + DeepONetCartesianProd + PODDeepONet + + +Fully Connected Neural Network +------------------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + get_activation + NN + FNN + PFNN + Union + Callable + Sequence + Optional + + +Multiple Input Operators Network +-------------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + get_activation + NN + FNN + MIONetCartesianProd + PODMIONet + Optional + Callable + + +Model +----- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Model + + diff --git a/docs/apis/pinnx.problem.rst b/docs/apis/pinnx.problem.rst new file mode 100644 index 0000000..a5f3d0c --- /dev/null +++ b/docs/apis/pinnx.problem.rst @@ -0,0 +1,122 @@ +``pinnx.problem`` module +======================== + +.. currentmodule:: pinnx.problem +.. automodule:: pinnx.problem + +Base Problem Class +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Problem + + +Dataset Function +---------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Function + + +General Dataset +--------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + DataSet + + +Multifidelity Dataset +--------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + MfFunc + MfDataSet + + +Quadruple Point Dataset +----------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + QuadrupleDataset + QuadrupleCartesianProd + + +Triple Point Dataset +-------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + TripleDataset + TripleCartesianProd + + +Forward PDE +----------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + FPDE + TimeFPDE + + +Inverse PDE +----------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + IDE + + +PDE Operator +------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + PDEOperator + PDEOperatorCartesianProd + + +PDE +--- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + PDE + TimePDE + + diff --git a/docs/apis/pinnx.rst b/docs/apis/pinnx.rst new file mode 100644 index 0000000..43c0552 --- /dev/null +++ b/docs/apis/pinnx.rst @@ -0,0 +1,17 @@ +``pinnx`` module +================ + +.. currentmodule:: pinnx +.. automodule:: pinnx + +Trainer +------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + Trainer + + diff --git a/docs/apis/pinnx.utils.rst b/docs/apis/pinnx.utils.rst new file mode 100644 index 0000000..b67921f --- /dev/null +++ b/docs/apis/pinnx.utils.rst @@ -0,0 +1,156 @@ +``pinnx.utils`` module +====================== + +.. currentmodule:: pinnx.utils +.. automodule:: pinnx.utils + +Dict and Array Converters +------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + array_to_dict + dict_to_array + + +Display training progress. +-------------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + pformat + tree_repr + TrainingDisplay + training_display + + +Array Operations +---------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + is_tensor + istensorlist + convert_to_array + hstack + zero_padding + Sequence + + +External Functions +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + apply + standardize + saveplot + plot_loss_history + save_loss_history + plot_best_state + save_best_state + dat_to_csv + isclose + smart_numpy + Axes3D + Pool + + +Internal Functions +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + wraps + apply + timing + merge_dict + subdict + check_not_none + run_if_all_none + run_if_any_none + vectorize + return_tensor + to_numpy + make_dict + save_animation + list_to_str + tree_repr + get_num_args + get_activation + Callable + Union + + +Loss Functions +-------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + mean_absolute_error + mean_squared_error + mean_l2_relative_error + softmax_cross_entropy + get_loss + LOSS_DICT + + +Sampler +------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + BatchSampler + + +Sampling +-------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + sample + + +Transformer +----------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: classtemplate.rst + + LabelBinarizer + Transformer + Identity + StringEncoder + LogN + CategoricalEncoder + LabelEncoder + Normalize + Pipeline + + diff --git a/docs/auto_generater.py b/docs/auto_generater.py new file mode 100644 index 0000000..b771e51 --- /dev/null +++ b/docs/auto_generater.py @@ -0,0 +1,370 @@ +# -*- coding: utf-8 -*- + +import importlib +import inspect +import os + +block_list = ['test', 'register_pytree_node', 'call', 'namedtuple', 'jit', 'wraps', 'index', 'function'] + + +def get_class_funcs(module): + classes, functions, others = [], [], [] + # Solution from: https://stackoverflow.com/questions/43059267/how-to-do-from-module-import-using-importlib + if "__all__" in module.__dict__: + names = module.__dict__["__all__"] + else: + names = [x for x in module.__dict__ if not x.startswith("_")] + for k in names: + data = getattr(module, k) + if not inspect.ismodule(data) and not k.startswith("_"): + if inspect.isfunction(data): + functions.append(k) + elif isinstance(data, type): + classes.append(k) + else: + others.append(k) + + return classes, functions, others + + +def _write_module(module_name, automodule, filename, header=None, template=False): + module = importlib.import_module(module_name) + classes, functions, others = get_class_funcs(module) + + fout = open(filename, 'w') + # write header + if header is None: + header = f'``{module_name}`` module' + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + fout.write(f'.. currentmodule:: {automodule} \n') + fout.write(f'.. automodule:: {automodule} \n\n') + + # write autosummary + fout.write('.. autosummary::\n') + if template: + fout.write(' :template: classtemplate.rst\n') + fout.write(' :toctree: generated/\n\n') + for m in functions: + fout.write(f' {m}\n') + for m in classes: + fout.write(f' {m}\n') + for m in others: + fout.write(f' {m}\n') + + fout.close() + + +def _write_submodules(module_name, filename, header=None, submodule_names=(), section_names=()): + fout = open(filename, 'w') + # write header + if header is None: + header = f'``{module_name}`` module' + else: + header = header + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + fout.write(f'.. currentmodule:: {module_name} \n') + fout.write(f'.. automodule:: {module_name} \n\n') + + # whole module + for i, name in enumerate(submodule_names): + module = importlib.import_module(module_name + '.' + name) + classes, functions, others = get_class_funcs(module) + + fout.write(section_names[i] + '\n') + fout.write('-' * len(section_names[i]) + '\n\n') + + # write autosummary + fout.write('.. autosummary::\n') + fout.write(' :toctree: generated/\n') + fout.write(' :nosignatures:\n') + fout.write(' :template: classtemplate.rst\n\n') + for m in functions: + fout.write(f' {m}\n') + for m in classes: + fout.write(f' {m}\n') + for m in others: + fout.write(f' {m}\n') + + fout.write(f'\n\n') + + fout.close() + + +def _write_subsections(module_name, + filename, + subsections: dict, + header: str = None): + fout = open(filename, 'w') + header = f'``{module_name}`` module' if header is None else header + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + fout.write(f'.. currentmodule:: {module_name} \n') + fout.write(f'.. automodule:: {module_name} \n\n') + + fout.write('.. contents::' + '\n') + fout.write(' :local:' + '\n') + fout.write(' :depth: 1' + '\n\n') + + for name, values in subsections.items(): + fout.write(name + '\n') + fout.write('-' * len(name) + '\n\n') + fout.write('.. autosummary::\n') + fout.write(' :toctree: generated/\n') + fout.write(' :nosignatures:\n') + fout.write(' :template: classtemplate.rst\n\n') + for m in values: + fout.write(f' {m}\n') + fout.write(f'\n\n') + + fout.close() + + +def _write_subsections_v2(module_path, + out_path, + filename, + subsections: dict, + header: str = None): + fout = open(filename, 'w') + header = f'``{out_path}`` module' if header is None else header + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + fout.write(f'.. currentmodule:: {out_path} \n') + fout.write(f'.. automodule:: {out_path} \n\n') + + fout.write('.. contents::' + '\n') + fout.write(' :local:' + '\n') + fout.write(' :depth: 1' + '\n\n') + + for name, subheader in subsections.items(): + module = importlib.import_module(f'{module_path}.{name}') + classes, functions, others = get_class_funcs(module) + + fout.write(subheader + '\n') + fout.write('-' * len(subheader) + '\n\n') + fout.write('.. autosummary::\n') + fout.write(' :toctree: generated/\n') + fout.write(' :nosignatures:\n') + fout.write(' :template: classtemplate.rst\n\n') + for m in functions: + fout.write(f' {m}\n') + for m in classes: + fout.write(f' {m}\n') + for m in others: + fout.write(f' {m}\n') + fout.write(f'\n\n') + + fout.close() + + +def _write_subsections_v3(module_path, + out_path, + filename, + subsections: dict, + header: str = None): + fout = open(filename, 'w') + header = f'``{out_path}`` module' if header is None else header + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + fout.write(f'.. currentmodule:: {out_path} \n') + fout.write(f'.. automodule:: {out_path} \n\n') + + fout.write('.. contents::' + '\n') + fout.write(' :local:' + '\n') + fout.write(' :depth: 2' + '\n\n') + + for section in subsections: + fout.write(subsections[section]['header'] + '\n') + fout.write('-' * len(subsections[section]['header']) + '\n\n') + + fout.write(f'.. currentmodule:: {out_path}.{section} \n') + fout.write(f'.. automodule:: {out_path}.{section} \n\n') + + for name, subheader in subsections[section]['content'].items(): + module = importlib.import_module(f'{module_path}.{section}.{name}') + classes, functions, others = get_class_funcs(module) + + fout.write(subheader + '\n') + fout.write('~' * len(subheader) + '\n\n') + fout.write('.. autosummary::\n') + fout.write(' :toctree: generated/\n') + fout.write(' :nosignatures:\n') + fout.write(' :template: classtemplate.rst\n\n') + for m in functions: + fout.write(f' {m}\n') + for m in classes: + fout.write(f' {m}\n') + for m in others: + fout.write(f' {m}\n') + fout.write(f'\n\n') + + fout.close() + + +def _write_subsections_v4(module_path, + filename, + subsections: dict, + header: str = None): + fout = open(filename, 'w') + header = f'``{module_path}`` module' if header is None else header + fout.write(header + '\n') + fout.write('=' * len(header) + '\n\n') + + fout.write('.. contents::' + '\n') + fout.write(' :local:' + '\n') + fout.write(' :depth: 1' + '\n\n') + + for name, (subheader, out_path) in subsections.items(): + + module = importlib.import_module(f'{module_path}.{name}') + classes, functions, others = get_class_funcs(module) + + fout.write(subheader + '\n') + fout.write('-' * len(subheader) + '\n\n') + + fout.write(f'.. currentmodule:: {out_path} \n') + fout.write(f'.. automodule:: {out_path} \n\n') + + fout.write('.. autosummary::\n') + fout.write(' :toctree: generated/\n') + fout.write(' :nosignatures:\n') + fout.write(' :template: classtemplate.rst\n\n') + for m in functions: + fout.write(f' {m}\n') + for m in classes: + fout.write(f' {m}\n') + for m in others: + fout.write(f' {m}\n') + fout.write(f'\n\n') + + fout.close() + + +def _get_functions(obj): + return set([n for n in dir(obj) + if (n not in block_list # not in blacklist + and callable(getattr(obj, n)) # callable + and not isinstance(getattr(obj, n), type) # not class + and n[0].islower() # starts with lower char + and not n.startswith('__') # not special methods + ) + ]) + + +def _import(mod, klass=None, is_jax=False): + obj = importlib.import_module(mod) + if klass: + obj = getattr(obj, klass) + return obj, ':meth:`{}.{}.{{}}`'.format(mod, klass) + else: + if not is_jax: + return obj, ':obj:`{}.{{}}`'.format(mod) + else: + from docs import implemented_jax_funcs + return implemented_jax_funcs, ':obj:`{}.{{}}`'.format(mod) + + +def main(): + os.makedirs('apis/', exist_ok=True) + + + module_and_name = [ + ('base', 'Base Geometry Class'), + ('geometry_1d', 'Geometry in 1D'), + ('geometry_2d', 'Geometry in 2D'), + ('geometry_3d', 'Geometry in 3D'), + ('geometry_nd', 'Geometry in ND'), + ('pointcloud', 'Point Cloud'), + ('timedomain', 'Time Domain'), + ] + + _write_submodules(module_name='pinnx.geometry', + filename='apis/pinnx.geometry.rst', + header='``pinnx.geometry`` module', + submodule_names=[k[0] for k in module_and_name], + section_names=[k[1] for k in module_and_name]) + + module_and_name = [ + ('base', 'Base Initial and Boundary Conditions Class'), + ('boundary_conditions', 'Boundary Conditions'), + ('initial_conditions', 'Initial Conditions'), + ] + + _write_submodules(module_name='pinnx.icbc', + filename='apis/pinnx.icbc.rst', + header='``pinnx.icbc`` module', + submodule_names=[k[0] for k in module_and_name], + section_names=[k[1] for k in module_and_name]) + + module_and_name = [ + ('base', 'Base Neural Network Class'), + ('convert', 'Dict and Array Converters'), + ('deeponet_strategy', 'DeepONet Strategy'), + ('deeponet', 'DeepONet'), + ('fnn', 'Fully Connected Neural Network'), + ('mionet', 'Multiple Input Operators Network'), + ('model', 'Model'), + ] + + _write_submodules(module_name='pinnx.nn', + filename='apis/pinnx.nn.rst', + header='``pinnx.nn`` module', + submodule_names=[k[0] for k in module_and_name], + section_names=[k[1] for k in module_and_name]) + + module_and_name = [ + ('base', 'Base Problem Class'), + ('dataset_function', 'Dataset Function'), + ('dataset_general', 'General Dataset'), + ('dataset_mf', 'Multifidelity Dataset'), + ('dataset_quadruple', 'Quadruple Point Dataset'), + ('dataset_triple', 'Triple Point Dataset'), + ('fpde', 'Forward PDE'), + ('ide', 'Inverse PDE'), + ('pde_operator', 'PDE Operator'), + ('pde', 'PDE'), + ] + + _write_submodules(module_name='pinnx.problem', + filename='apis/pinnx.problem.rst', + header='``pinnx.problem`` module', + submodule_names=[k[0] for k in module_and_name], + section_names=[k[1] for k in module_and_name]) + + module_and_name = [ + ('_convert', 'Dict and Array Converters'), + ('_display', 'Display training progress.'), + ('array_ops', 'Array Operations'), + ('external', 'External Functions'), + ('internal', 'Internal Functions'), + ('losses', 'Loss Functions'), + ('sampler', 'Sampler'), + ('sampling', 'Sampling'), + ('transformers', 'Transformer'), + ] + + _write_submodules(module_name='pinnx.utils', + filename='apis/pinnx.utils.rst', + header='``pinnx.utils`` module', + submodule_names=[k[0] for k in module_and_name], + section_names=[k[1] for k in module_and_name]) + + # module_and_name = [ + # ('_trainer', 'Trainer'), + # ('callbacks', 'Callbacks'), + # ('fnspace', 'Function Space'), + # ('grad', 'Automatic Differentiation'), + # ('metrics', 'Metrics'), + # ] + # + # _write_submodules(module_name='pinnx', + # filename='apis/pinnx.rst', + # header='``pinnx`` module', + # submodule_names=[k[0] for k in module_and_name], + # section_names=[k[1] for k in module_and_name]) + + + +if __name__ == '__main__': + main() \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 83eb221..3b77390 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,9 +29,14 @@ import os import sys +sys.path.insert(0, os.path.abspath(os.path.curdir)) sys.path.insert(0, os.path.abspath('../')) import pinnx +import auto_generater +auto_generater.main() + +os.makedirs('apis/', exist_ok=True) # -- Project information ----------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 299c0e8..bb2b516 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -66,3 +66,18 @@ See also the BDP ecosystem We are building the `brain dynamics programming ecosystem `_. +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: API Documentation + + apis/pinnx.rst + apis/pinnx.callbacks.rst + apis/pinnx.fnspace.rst + apis/pinnx.grad.rst + apis/pinnx.geometry.rst + apis/pinnx.icbc.rst + apis/pinnx.metrics.rst + apis/pinnx.nn.rst + apis/pinnx.problem.rst + apis/pinnx.utils.rst \ No newline at end of file diff --git a/pinnx/metrics.py b/pinnx/metrics.py index db7b260..164e2dd 100644 --- a/pinnx/metrics.py +++ b/pinnx/metrics.py @@ -20,6 +20,7 @@ def _accuracy(y_true, y_pred): def accuracy(y_true, y_pred): + """Computes accuracy across nested structures of labels and predictions.""" return jax.tree_util.tree_map(_accuracy, y_true, y_pred, is_leaf=u.math.is_quantity) @@ -28,11 +29,11 @@ def _l2_relative_error(y_true, y_pred): def l2_relative_error(y_true, y_pred): + """Computes L2 relative error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(_l2_relative_error, y_true, y_pred, is_leaf=u.math.is_quantity) def _nanl2_relative_error(y_true, y_pred): - """Return the L2 relative error treating Not a Numbers (NaNs) as zero.""" err = y_true - y_pred err = u.math.nan_to_num(err) y_true = u.math.nan_to_num(y_true) @@ -40,11 +41,11 @@ def _nanl2_relative_error(y_true, y_pred): def nanl2_relative_error(y_true, y_pred): + """Computes L2 relative error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(_nanl2_relative_error, y_true, y_pred, is_leaf=u.math.is_quantity) def _mean_l2_relative_error(y_true, y_pred): - """Compute the average of L2 relative error along the first axis.""" return u.math.mean( u.linalg.norm(y_true - y_pred, axis=1) / u.linalg.norm(y_true, axis=1) @@ -52,6 +53,7 @@ def _mean_l2_relative_error(y_true, y_pred): def mean_l2_relative_error(y_true, y_pred): + """Computes mean L2 relative error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(_mean_l2_relative_error, y_true, y_pred, is_leaf=u.math.is_quantity) @@ -60,6 +62,7 @@ def _absolute_percentage_error(y_true, y_pred): def mean_absolute_percentage_error(y_true, y_pred): + """Computes mean absolute percentage error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(lambda x, y: _absolute_percentage_error(x, y).mean(), y_true, y_pred, @@ -74,6 +77,7 @@ def max_absolute_percentage_error(y_true, y_pred): def absolute_percentage_error_std(y_true, y_pred): + """Computes standard deviation of absolute percentage error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(lambda x, y: _absolute_percentage_error(x, y).std(), y_true, y_pred, @@ -85,6 +89,7 @@ def _mean_squared_error(y_true, y_pred): def mean_squared_error(y_true, y_pred): + """Computes mean squared error across nested structures of labels and predictions.""" return jax.tree_util.tree_map(_mean_squared_error, y_true, y_pred, is_leaf=u.math.is_quantity) diff --git a/pinnx/nn/output.py b/pinnx/nn/output.py deleted file mode 100644 index 36aa293..0000000 --- a/pinnx/nn/output.py +++ /dev/null @@ -1,24 +0,0 @@ -# Copyright 2024 BDP Ecosystem Limited. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# ============================================================================== - -from typing import Dict - -import brainstate as bst -import brainunit as u - -__all__ = [ - 'Output', -] - From 3681a6503f08c458f8b7d671baf2ebe4bc8dbf7b Mon Sep 17 00:00:00 2001 From: Sichao He <1310722434@qq.com> Date: Sat, 14 Dec 2024 00:08:03 +0800 Subject: [PATCH 2/2] Remove autogen .rst files --- .gitignore | 7 +- docs/apis/pinnx.geometry.rst | 117 -------------------------- docs/apis/pinnx.icbc.rst | 50 ----------- docs/apis/pinnx.nn.rst | 108 ------------------------ docs/apis/pinnx.problem.rst | 122 --------------------------- docs/apis/pinnx.utils.rst | 156 ----------------------------------- 6 files changed, 6 insertions(+), 554 deletions(-) delete mode 100644 docs/apis/pinnx.geometry.rst delete mode 100644 docs/apis/pinnx.icbc.rst delete mode 100644 docs/apis/pinnx.nn.rst delete mode 100644 docs/apis/pinnx.problem.rst delete mode 100644 docs/apis/pinnx.utils.rst diff --git a/.gitignore b/.gitignore index 67c371b..8025c7c 100644 --- a/.gitignore +++ b/.gitignore @@ -31,4 +31,9 @@ docs/**/*.dat docs/**/*.npz .DS_Store -docs/apis/generated/ \ No newline at end of file +docs/apis/ +!docs/apis/pinnx.rst +!docs/apis/pinnx.callbacks.rst +!docs/apis/pinnx.fnspace.rst +!docs/apis/pinnx.grad.rst +!docs/apis/pinnx.metrics.rst \ No newline at end of file diff --git a/docs/apis/pinnx.geometry.rst b/docs/apis/pinnx.geometry.rst deleted file mode 100644 index ab22761..0000000 --- a/docs/apis/pinnx.geometry.rst +++ /dev/null @@ -1,117 +0,0 @@ -``pinnx.geometry`` module -========================= - -.. currentmodule:: pinnx.geometry -.. automodule:: pinnx.geometry - -Base Geometry Class -------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - AbstractGeometry - Geometry - CSGUnion - CSGDifference - CSGIntersection - - -Geometry in 1D --------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - sample - Geometry - Interval - Literal - Union - - -Geometry in 2D --------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - Disk - Ellipse - Polygon - Rectangle - StarShaped - Triangle - - -Geometry in 3D --------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - Rectangle - Hypercube - Hypersphere - Cuboid - Sphere - Union - Literal - - -Geometry in ND --------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - sample - isclose - Geometry - Hypercube - Hypersphere - Literal - - -Point Cloud ------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - isclose - BatchSampler - Geometry - PointCloud - - -Time Domain ------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - isclose - AbstractGeometry - Interval - Rectangle - Cuboid - Hypercube - TimeDomain - GeometryXTime - - diff --git a/docs/apis/pinnx.icbc.rst b/docs/apis/pinnx.icbc.rst deleted file mode 100644 index cccaeb7..0000000 --- a/docs/apis/pinnx.icbc.rst +++ /dev/null @@ -1,50 +0,0 @@ -``pinnx.icbc`` module -===================== - -.. currentmodule:: pinnx.icbc -.. automodule:: pinnx.icbc - -Base Initial and Boundary Conditions Class ------------------------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - AbstractGeometry - ICBC - Optional - Dict - - -Boundary Conditions -------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - BC - DirichletBC - Interface2DBC - NeumannBC - OperatorBC - PeriodicBC - PointSetBC - PointSetOperatorBC - RobinBC - - -Initial Conditions ------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - IC - - diff --git a/docs/apis/pinnx.nn.rst b/docs/apis/pinnx.nn.rst deleted file mode 100644 index 5ca4487..0000000 --- a/docs/apis/pinnx.nn.rst +++ /dev/null @@ -1,108 +0,0 @@ -``pinnx.nn`` module -=================== - -.. currentmodule:: pinnx.nn -.. automodule:: pinnx.nn - -Base Neural Network Class -------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - NN - Optional - Callable - - -Dict and Array Converters -------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - DictToArray - ArrayToDict - - -DeepONet Strategy ------------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - abstractmethod - ABC - DeepONetStrategy - SingleOutputStrategy - IndependentStrategy - SplitBothStrategy - SplitBranchStrategy - SplitTrunkStrategy - - -DeepONet --------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - DeepONet - DeepONetCartesianProd - PODDeepONet - - -Fully Connected Neural Network ------------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - get_activation - NN - FNN - PFNN - Union - Callable - Sequence - Optional - - -Multiple Input Operators Network --------------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - get_activation - NN - FNN - MIONetCartesianProd - PODMIONet - Optional - Callable - - -Model ------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - Model - - diff --git a/docs/apis/pinnx.problem.rst b/docs/apis/pinnx.problem.rst deleted file mode 100644 index a5f3d0c..0000000 --- a/docs/apis/pinnx.problem.rst +++ /dev/null @@ -1,122 +0,0 @@ -``pinnx.problem`` module -======================== - -.. currentmodule:: pinnx.problem -.. automodule:: pinnx.problem - -Base Problem Class ------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - Problem - - -Dataset Function ----------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - Function - - -General Dataset ---------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - DataSet - - -Multifidelity Dataset ---------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - MfFunc - MfDataSet - - -Quadruple Point Dataset ------------------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - QuadrupleDataset - QuadrupleCartesianProd - - -Triple Point Dataset --------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - TripleDataset - TripleCartesianProd - - -Forward PDE ------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - FPDE - TimeFPDE - - -Inverse PDE ------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - IDE - - -PDE Operator ------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - PDEOperator - PDEOperatorCartesianProd - - -PDE ---- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - PDE - TimePDE - - diff --git a/docs/apis/pinnx.utils.rst b/docs/apis/pinnx.utils.rst deleted file mode 100644 index b67921f..0000000 --- a/docs/apis/pinnx.utils.rst +++ /dev/null @@ -1,156 +0,0 @@ -``pinnx.utils`` module -====================== - -.. currentmodule:: pinnx.utils -.. automodule:: pinnx.utils - -Dict and Array Converters -------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - array_to_dict - dict_to_array - - -Display training progress. --------------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - pformat - tree_repr - TrainingDisplay - training_display - - -Array Operations ----------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - is_tensor - istensorlist - convert_to_array - hstack - zero_padding - Sequence - - -External Functions ------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - apply - standardize - saveplot - plot_loss_history - save_loss_history - plot_best_state - save_best_state - dat_to_csv - isclose - smart_numpy - Axes3D - Pool - - -Internal Functions ------------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - wraps - apply - timing - merge_dict - subdict - check_not_none - run_if_all_none - run_if_any_none - vectorize - return_tensor - to_numpy - make_dict - save_animation - list_to_str - tree_repr - get_num_args - get_activation - Callable - Union - - -Loss Functions --------------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - mean_absolute_error - mean_squared_error - mean_l2_relative_error - softmax_cross_entropy - get_loss - LOSS_DICT - - -Sampler -------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - BatchSampler - - -Sampling --------- - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - sample - - -Transformer ------------ - -.. autosummary:: - :toctree: generated/ - :nosignatures: - :template: classtemplate.rst - - LabelBinarizer - Transformer - Identity - StringEncoder - LogN - CategoricalEncoder - LabelEncoder - Normalize - Pipeline - -