diff --git a/docs/api/pinnicle.physics.rst b/docs/api/pinnicle.physics.rst index f348967..fa88a64 100644 --- a/docs/api/pinnicle.physics.rst +++ b/docs/api/pinnicle.physics.rst @@ -33,6 +33,14 @@ pinnicle.physics.continuity module :undoc-members: :show-inheritance: +pinnicle.physics.dummy module +----------------------------- + +.. automodule:: pinnicle.physics.dummy + :members: + :undoc-members: + :show-inheritance: + pinnicle.physics.stressbalance module ------------------------------------- diff --git a/docs/examples/advanced.rst b/docs/examples/advanced.rst new file mode 100644 index 0000000..0e5015b --- /dev/null +++ b/docs/examples/advanced.rst @@ -0,0 +1,61 @@ +Advanced Features in PINNICLE +============================= + +PINNICLE is under active development, and several **advanced**/**experimental** features are listed here in alphabetical order: + +Additional Loss Functions +------------------------- + +It is possible to add additional loss functions to the total loss. Here is an example: + +.. code-block:: python + + vel_loss = {} + vel_loss['name'] = "vel MAPE" + vel_loss['function'] = "MAPE" + vel_loss['weight'] = 1.0e-6 + hp["additional_loss"] = {"vel":vel_loss} + +In this example, we define a `dict` which contains: +- `name`: A user-defined name for the loss function. +- `function`: A function ID from `LOSS_DICT` in `deepxde.losses `_ or `pinnicle.utils.data_misfit `_. These lists include most commonly used loss functions, such as `"mean"`, `"MAE"`, `"MSE"`, `"MAPE"`, `"zero"`, `"VEL_LOG"`, `"MEAN_SQUARE_LOG"`, etc. Before writing your own loss function, refer to these lists, as these functions are optimized with the backends. +- `weight`: the weight of this loss function. + +Finally, add the new `dict` to `hp["additional_loss"]` with the key indicating the variable to which this loss function should be applied. In the above example, we are adding the mean absolute percentage error of the velocity magnitude to the total loss. + +Dummy Equations +--------------- + +PINNICLE provides `Dummy `_ physics, which allows you to train the neural network using data only. Here is an example: + +.. code-block:: python + + dummy = {} + dummy["output"] = ['u', 's', 'C'] + hp["equations"] = {"DUMMY": dummy} + +In this example, we define a `dict` with a key `output`, where the value is a list of three output variables. Then, we add this `dict` to `hp['equations']` with the key `DUMMY` (all uppercase). Additionally, you need to provide the data for `u`, `s`, and `C` in the `data` section, similar to other examples. The neural network will then be trained solely with the provided data. + +By default, the `Dummy` physics already has `x` and `y` as `input`. If there is no need to change this, only the `output` needs to be defined. + + +Architecture of the Neural Network +---------------------------------- + +PINNICLE supports both fully connected neural networks and parallel neural networks. To choose one, simply set `hp["is_parallel"]` to `False` or `True`. Currently, PINNICLE only supports parallel networks for each individual output, and all these networks are of the same size. + +Another feature of the neural network architecture is that you can set the number of neurons and layers as follows: + +.. code-block:: python + + hp["num_neurons"] = 20 + hp["num_layers"] = 4 + +This configuration creates a network with 4 layers, each containing 20 neurons. Alternatively, you can define the number of neurons in each layer using a list: + +.. code-block:: python + + hp["num_neurons"] = [128, 64, 32, 16] + +In this case, the number of layers is inferred from the length of the list, creating a network with 4 layers having 128, 64, 32, and 16 neurons respectively. + diff --git a/docs/examples/pinn.mc.rst b/docs/examples/couple.rst similarity index 100% rename from docs/examples/pinn.mc.rst rename to docs/examples/couple.rst diff --git a/docs/examples/pinn.mcssa.rst b/docs/examples/mc.rst similarity index 100% rename from docs/examples/pinn.mcssa.rst rename to docs/examples/mc.rst diff --git a/docs/examples/pinn.ssa.rst b/docs/examples/ssa.rst similarity index 100% rename from docs/examples/pinn.ssa.rst rename to docs/examples/ssa.rst diff --git a/docs/index.rst b/docs/index.rst index 229c41c..95108ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,7 +47,7 @@ User guide .. toctree:: :maxdepth: 1 - pinn_examples + pinnicle_examples API reference diff --git a/docs/installation.rst b/docs/installation.rst index 9e058c6..440ac9b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -18,7 +18,7 @@ In the future, PINNICLE will support the following backends: - To install and use the package, you should clone the folder to your local machine and put it along with your project scripts:: - $ git clone https://github.com/enigne/PINNICLE.git + $ git clone https://github.com/ISSMteam/PINNICLE.git * Other dependencies diff --git a/docs/pinn_examples.rst b/docs/pinn_examples.rst deleted file mode 100644 index 769e09c..0000000 --- a/docs/pinn_examples.rst +++ /dev/null @@ -1,28 +0,0 @@ -Examples -========================= - -Here are some examples of solving ice sheet modeling problems using PINNICLE - -Stress Balance --------------- - -.. toctree:: - :maxdepth: 1 - - examples/pinn.ssa - -Mass Balance ------------- - -.. toctree:: - :maxdepth: 1 - - examples/pinn.mc - -Coupling -------------------- - -.. toctree:: - :maxdepth: 1 - - examples/pinn.mcssa diff --git a/docs/pinnicle_examples.rst b/docs/pinnicle_examples.rst new file mode 100644 index 0000000..8f979ee --- /dev/null +++ b/docs/pinnicle_examples.rst @@ -0,0 +1,23 @@ +Examples +======== + +Here are some examples of solving ice sheet modeling problems using PINNICLE + +Basic +----- + +.. toctree:: + :maxdepth: 1 + + examples/ssa + examples/mc + examples/couple + +Advanced +-------- + +.. toctree:: + :maxdepth: 2 + + examples/advanced +