Skip to content

Commit

Permalink
review tutorial
Browse files Browse the repository at this point in the history
  • Loading branch information
@fschuch
fschuch committed Oct 7, 2021
1 parent d41ef97 commit 678aa48
Showing 1 changed file with 105 additions and 105 deletions.
210 changes: 105 additions & 105 deletions docs/tutorial/parameters.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
{
"cell_type": "markdown",
"source": [
"# Parameters\n",
"\n",
"The computational and physical parameters are handled by `class xcompact3d_toolbox.Parameters`. It is built on top of [Traitlets](https://traitlets.readthedocs.io/en/stable/index.html), which aims to make the parameters compatible with what xcompact3d expects, and also brings some advantages:\n",
"\n",
"* Attributes are type-checked;\n",
"* Default values, restrictions and conections between related parameters are applied where necessary;\n",
"* 'On change' callbacks for validation and observation;\n",
"# Parameters\r\n",
"\r\n",
"The computational and physical parameters are handled by `class xcompact3d_toolbox.Parameters`. It is built on top of [Traitlets](https://traitlets.readthedocs.io/en/stable/index.html), which aims to make the parameters compatible with what xcompact3d expects, and also brings some advantages:\r\n",
"\r\n",
"* Attributes are type-checked;\r\n",
"* Default values, restrictions and connections between related parameters are applied where necessary;\r\n",
"* 'On change' callbacks for validation and observation;\r\n",
"* Two-way linking with [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/)."
],
"metadata": {}
Expand Down Expand Up @@ -202,43 +202,43 @@
{
"cell_type": "markdown",
"source": [
"The class can also read the previous parameters format ([se more information here](https://github.com/fschuch/xcompact3d_toolbox/issues/7)):\n",
"\n",
"``` python\n",
"prm = x3d.Parameters(loadfile=\"incompact3d.prm\")\n",
"The class can also read the previous parameters format ([se more information here](https://github.com/fschuch/xcompact3d_toolbox/issues/7)):\r\n",
"\r\n",
"``` python\r\n",
"prm = x3d.Parameters(loadfile=\"incompact3d.prm\")\r\n",
"```"
],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"There are extra objects read and write the raw binary files from XCompact3d on-demand.\n",
"\n",
"* Read a binary field from the disc:\n",
"\n",
" ``` python\n",
" ux = prm.dataset.load_array(\"ux-0000.bin\")\n",
" ```\n",
"\n",
"* Read the entire time series for a given variable:\n",
"\n",
" ``` python\n",
" ux = prm.dataset.load_time_series(\"ux\")\n",
" ```\n",
" \n",
"* Read all variables for a given snapshot:\n",
"\n",
" ```python\n",
" snapshot = prm.dataset.load_snapshot(10)\n",
" ```\n",
"\n",
"* Write `xdmf` files, so the binary files can be open in any external visualization tool:\n",
"\n",
" ``` python\n",
" prm.dataset.write_xdmf()\n",
" ```\n",
"\n",
"There are extra objects read and write the raw binary files from XCompact3d on-demand.\r\n",
"\r\n",
"* Read a binary field from the disc:\r\n",
"\r\n",
" ``` python\r\n",
" ux = prm.dataset.load_array(\"ux-0000.bin\")\r\n",
" ```\r\n",
"\r\n",
"* Read the entire time series for a given variable:\r\n",
"\r\n",
" ``` python\r\n",
" ux = prm.dataset.load_time_series(\"ux\")\r\n",
" ```\r\n",
" \r\n",
"* Read all variables for a given snapshot:\r\n",
"\r\n",
" ```python\r\n",
" snapshot = prm.dataset.load_snapshot(10)\r\n",
" ```\r\n",
"\r\n",
"* Write `xdmf` files, so the binary files can be open in any external visualization tool:\r\n",
"\r\n",
" ``` python\r\n",
" prm.dataset.write_xdmf()\r\n",
" ```\r\n",
"\r\n",
"* Compute the coordinates, including support for mesh refinement in y:"
],
"metadata": {}
Expand All @@ -262,19 +262,19 @@
{
"cell_type": "markdown",
"source": [
"## Traitlets\n",
"\n",
"### Type-checking\n",
"\n",
"All parameters are type-checked, to make sure that they are what `Xcompact3d` expects. Use the cellcode below to see how a `TraitError` pops out when we try:\n",
"\n",
"```python\n",
"prm.itype = 10.5\n",
"prm.itype = -5\n",
"prm.itype = 20\n",
"prm.itype = 'sandbox'\n",
"\n",
"```\n"
"## Traitlets\r\n",
"\r\n",
"### Type-checking\r\n",
"\r\n",
"All parameters are type-checked, to make sure that they are what `Xcompact3d` expects. Use the cellcode below to see how a `TraitError` pops out when we try:\r\n",
"\r\n",
"```python\r\n",
"prm.itype = 10.5\r\n",
"prm.itype = -5\r\n",
"prm.itype = 20\r\n",
"prm.itype = 'sandbox'\r\n",
"\r\n",
"```\r\n"
],
"metadata": {}
},
Expand All @@ -295,28 +295,28 @@
{
"cell_type": "markdown",
"source": [
"Some parameters, like mesh points (`nx`, `ny` and `nz`), trigger a validation operation when a new value is attributed to them.\n",
"Due to restrictions at the FFT library, they must be equal to:\n",
"\n",
"$$\n",
"n_i = \\left\\{ \\begin{array}{ll} 2^{1+a} \\times 3^b \\times 5^c &\\mbox{if periodic,} \\\\ 2^{1+a} \\times 3^b \\times 5^c + 1 &\\mbox{otherwise,}\n",
"\\end{array} \\right.\n",
"$$\n",
"\n",
"where $a$, $b$ and $c$ are non negative integers. In addition, the derivatives stencil imposes that:\n",
"\n",
"$$\n",
"n_i \\ge \\left\\{ \\begin{array}{ll} 8 &\\mbox{if periodic,} \\\\ 9 &\\mbox{otherwise.}\n",
"\\end{array} \\right.\n",
"$$\n",
"\n",
"Again, give it a try at the cellcode below:\n",
"\n",
"```python\n",
"prm.nx = 129\n",
"prm.nx = 4\n",
"prm.nx = 60\n",
"prm.nx = 61\n",
"Some parameters, like mesh points (`nx`, `ny` and `nz`), trigger a validation operation when a new value is attributed to them.\r\n",
"Due to restrictions at the FFT library, they must be equal to:\r\n",
"\r\n",
"$$\r\n",
"n_i = \\left\\{ \\begin{array}{ll} 2^{1+a} \\times 3^b \\times 5^c &\\mbox{if periodic,} \\\\ 2^{1+a} \\times 3^b \\times 5^c + 1 &\\mbox{otherwise,}\r\n",
"\\end{array} \\right.\r\n",
"$$\r\n",
"\r\n",
"where $a$, $b$ and $c$ are non negative integers. In addition, the derivatives stencil imposes that:\r\n",
"\r\n",
"$$\r\n",
"n_i \\ge \\left\\{ \\begin{array}{ll} 8 &\\mbox{if periodic,} \\\\ 9 &\\mbox{otherwise.}\r\n",
"\\end{array} \\right.\r\n",
"$$\r\n",
"\r\n",
"Again, give it a try at the cellcode below:\r\n",
"\r\n",
"```python\r\n",
"prm.nx = 129\r\n",
"prm.nx = 4\r\n",
"prm.nx = 60\r\n",
"prm.nx = 61\r\n",
"```"
],
"metadata": {}
Expand All @@ -338,7 +338,7 @@
{
"cell_type": "markdown",
"source": [
"Other parameters, like mesh resolution (`dx`, `dy` and `dz`), are automaticaly updated when any new atribution occurs to mesh points and/or domain size. Let's create a quick print functions to play with:"
"Other parameters, like mesh resolution (`dx`, `dy` and `dz`), are automatically updated when any new attribution occurs to mesh points and/or domain size. Let's create a quick print functions to play with:"
],
"metadata": {}
},
Expand Down Expand Up @@ -426,20 +426,20 @@
{
"cell_type": "markdown",
"source": [
"Boundary conditions are observed as well. Xcompact3d allows three different BC for velocity:\n",
"\n",
"* Periodic `0`;\n",
"* Free-slip `1`;\n",
"* Dirichlet `2`.\n",
"\n",
"They can be assigned individualy for each of the six boundaries:\n",
"\n",
"* `nclx1` and `nclxn`, where $x=0$ and $x=xlx$;\n",
"* `ncly1` and `nclyn`, where $y=0$ and $y=yly$;\n",
"* `nclz1` and `nclzn`, where $z=0$ and $z=zlz$.\n",
"\n",
"It leads to 5 possibilities (`00`, `11`, `12`, `21` and `22`), because both boundary must be periodic, or not, so `0` cannot be combined.\n",
"\n",
"Boundary conditions are observed as well. Xcompact3d allows three different BC for velocity:\r\n",
"\r\n",
"* Periodic `0`;\r\n",
"* Free-slip `1`;\r\n",
"* Dirichlet `2`.\r\n",
"\r\n",
"They can be assigned individually for each of the six boundaries:\r\n",
"\r\n",
"* `nclx1` and `nclxn`, where $x=0$ and $x=xlx$;\r\n",
"* `ncly1` and `nclyn`, where $y=0$ and $y=yly$;\r\n",
"* `nclz1` and `nclzn`, where $z=0$ and $z=zlz$.\r\n",
"\r\n",
"It leads to 5 possibilities (`00`, `11`, `12`, `21` and `22`), because both boundary must be periodic, or not, so `0` cannot be combined.\r\n",
"\r\n",
"Let's check it out, we are starting with:"
],
"metadata": {}
Expand Down Expand Up @@ -560,9 +560,9 @@
{
"cell_type": "markdown",
"source": [
"Traitlets types constructors have a `tag` method to store metadata in a dictionary. In the case of Xcompact3d-toolbox, two are especially useful:\n",
"\n",
"* `group` defines to what namespace a given parameter belongs when the class is written to `.i3d` file (`.write()` method) or read from `.i3d` or `.prm` files (`.load()` method), parameters without a group are ignored for both methods;\n",
"Traitlets types constructors have a `tag` method to store metadata in a dictionary. In the case of Xcompact3d-toolbox, two are especially useful:\r\n",
"\r\n",
"* `group` defines to what namespace a given parameter belongs when the class is written to `.i3d` file (`.write()` method) or read from `.i3d` or `.prm` files (`.load()` method), parameters without a group are ignored for both methods;\r\n",
"* `desc` contains a brief description of each parameter that is shown on screen as we saw above, and also printed with the `.write()` method."
],
"metadata": {}
Expand All @@ -577,9 +577,9 @@
{
"cell_type": "markdown",
"source": [
"You probably would like to add more parameters for your own flow configuration, or because some of them were not implemented yet (it is a work in progress).\n",
"\n",
"To do so, any auxiliar varible can be included after initialization, like:"
"You probably would like to add more parameters for your own flow configuration, or because some of them were not implemented yet (it is a work in progress).\r\n",
"\r\n",
"To do so, any auxiliar variable can be included after initialization, like:"
],
"metadata": {}
},
Expand All @@ -595,8 +595,8 @@
{
"cell_type": "markdown",
"source": [
"It was called auxiliar variable because, in this way, it will be available only for the Python aplication.\n",
"\n",
"It was called auxiliar variable because, in this way, it will be available only for the Python application.\r\n",
"\r\n",
"In order to include it at the `.i3d` file and make it available for XCompact3d, we can create a subclass that inherits all the functionality from `xcompact3d_toolbox.Parameters`:"
],
"metadata": {}
Expand Down Expand Up @@ -651,7 +651,7 @@
"source": [
"<div class=\"alert alert-info\">\r\n",
"\r\n",
"For an interactive experience [launch this tutorial on Binder](https://mybinder.org/v2/gh/fschuch/xcompact3d_toolbox/main?labpath=.%2Fdocs%2Fexamples), the widgets are not so responsive when disconnected from a Python application.\r\n",
"For an interactive experience [launch this tutorial on Binder](https://mybinder.org/v2/gh/fschuch/xcompact3d_toolbox/main?labpath=.%2Fdocs%2Ftutorial), the widgets are not so responsive when disconnected from a Python application.\r\n",
"\r\n",
"</div>"
],
Expand All @@ -660,10 +660,10 @@
{
"cell_type": "markdown",
"source": [
"To conclude this part of the tutorial, let's see another option to handle the parameters. The class `ParametersGui` is a subclass of `Parameters`, and includes all the features described above. In addition, `ParametersGui` offers an user interface with [IPywidgets](https://ipywidgets.readthedocs.io/en/stable/index.html).\n",
"\n",
"It is still under development, more parameters and features are going to be included soon, as well as more widgets.\n",
"\n",
"To conclude this part of the tutorial, let's see another option to handle the parameters. The class `ParametersGui` is a subclass of `Parameters`, and includes all the features described above. In addition, `ParametersGui` offers an user interface with [IPywidgets](https://ipywidgets.readthedocs.io/en/stable/index.html).\r\n",
"\r\n",
"It is still under development, more parameters and features are going to be included soon, as well as more widgets.\r\n",
"\r\n",
"Just like before, we start with:"
],
"metadata": {}
Expand Down Expand Up @@ -696,8 +696,8 @@
{
"cell_type": "markdown",
"source": [
"You can play around with the widgets above and see the effect of the observations made previously.\n",
"\n",
"You can play around with the widgets above and see the effect of the observations made previously.\r\n",
"\r\n",
"Notice that the [Traitlets](https://traitlets.readthedocs.io/en/stable/index.html) parameters are related to the value at their widgets in a **two-way link**, in this way, a print will show the actual value on the widgets:"
],
"metadata": {}
Expand All @@ -714,8 +714,8 @@
{
"cell_type": "markdown",
"source": [
"Give it a try, modify the values at the widgets and print them again.\n",
"\n",
"Give it a try, modify the values at the widgets and print them again.\r\n",
"\r\n",
"It also works on the other way, set a new value to a parameters will change its widget, try it:"
],
"metadata": {}
Expand Down Expand Up @@ -748,7 +748,7 @@
{
"cell_type": "markdown",
"source": [
"A last example is about the domain decomposition for parallel computation, Xcompact3d uses [2DECOMP&FFT](http://www.2decomp.org/).\n",
"A last example is about the domain decomposition for parallel computation, Xcompact3d uses [2DECOMP&FFT](http://www.2decomp.org/).\r\n",
"The available options for `p_row` and `p_col` are presented as functions of the number of computational cores `ncores`, notice that `p_row * p_col = ncores` should be respected and `p_row * p_col = 0` activates the auto-tunning mode. The widgets are prepared to respect these restrictions:"
],
"metadata": {}
Expand Down

0 comments on commit 678aa48

Please sign in to comment.