(sec-user-run-pylith-parameter-gui)=
# PyLith Parameter Viewer

:::{note}
New in v2.2.0
:::

The PyLith Parameter Viewer provides a graphical user interface for viewing the parameters associated with a PyLith simulation and the version information for PyLith and its dependencies.
This viewer is an updated and interactive interface to the information generated by the [`pylith_dumpparameters`](sec-user-run-pylith-pylith-dumpparameters) script.
It displays the hiearchy of components and the parameters for each one, including default values.

## Installation

The PyLith Parameter Viewer is included in the PyLith binary distributions and PyLith Docker container for versions 2.1.5 and later.
Additionally, the PyLith Installer will install the Parameter Viewer by default.
For manual installation you can download the PyLith Parameter Viewer tarball from the PyLith software page <https://geodynamics.org/resources/pylith/supportingdocs/>.
After downloading the tarball, unpack it.
We recommend unpacking the tarball in the top-level PyLith directory.

```{code-block} console
$ tar -xvf pylith_parameters-1.1.0.tgz
```

## Running the Parameter Viewer

The steps to run the parameter viewer are:

1. Generate the parameter JSON file.
2. Start the web server (if not already running).
3. Load the parameter JSON file.

### Generate the parameter JSON file

The parameter viewer uses a JSON file with all of the parameters collected from `cfg` files, command line arguments, etc as input.
This file can be generated using {ref}`sec-user-run-pylith-pylith-dumpparameters`) and, by default, it will be generated whenever a PyLith simulation is run.
When using `pylith_dumpparameters` the name of the parameter file can be set via a command line argument.
When using PyLith the DumpParametersJSON component contains a property for the name of the file.
You can set the filename on the command line

```{code-block} console
$ pylith --dump_parameters.filename=FILENAME.json
```

or within a `cfg` file

```{code-block} cfg
[pylithapp.dump_parameters]
filename = FILENAME.json
```

Currently, the JSON parameter file cannot be used to run a PyLith simulation.
This feature will be added in an upcoming release.

### Start the web server

Change to the directory containing the `pylith_paramviewer` script (usually the `parametersgui` directory under the top-level `pylith` directory), and run the `pylith_paramviewer` script.
This will start a simple Python-based web server on your local computer.
Alternatively, you can use the online version at <https://geodynamics.github.io/pylith_parameters/>.

```{code-block} console
$ cd parametersgui
$ ./pylith_paramviewer
```

The script will instruct you to point your web browswer to a local port on your computer.
The default is <http://127.0.0.1:9000>.
You can change the default port using the `--port` command line argument to the `pylith_paramviewer` script.

## Using the Parameter Viewer

When you point your web browser to the correct port, you should see the PyLith Parameter Viewer as shown in {numref}`fig:parameters:gui:startup`.
Click the `Choose File` button and navigate to the desired JSON parameter file.
The viewer tarball includes a sample parameter file `sample_parameters.json`.
Click the `Reload` button to reload the same JSON parameter file if you regenerate it.
To select a new JSON parameter file, click the `Choose File` button and navigate to the desired file.

:::{figure-md} fig:parameters:gui:startup
<img src="figs/paramgui_startup.*" alt="Parameter Viewer screenshot at startup" width="100%" style="border: 1px solid #000"/>

Screenshot of PyLith Parameter Viewer in web browser upon startup.
:::

### Version Information

Click on the `Version` tab to examine the version information.
This tab displays the same version information shown with the `--version` command line argument to `pylith` in an easy to read layout.
This includes information about the platform on which `pylith` or `pylith_dumpparameters` was run, the PyLith version, and versions of the dependencies, as shown in {numref}`fig:parameters:gui:version`.

:::{figure-md} fig:parameters:gui:version
<img src="figs/paramgui_version.*" alt="Parameter Viewer screenshot of version information" width="100%" style="border: 1px solid #000"/>

Screenshot of `Version` tab of the PyLith Parameter Viewer with sample JSON parameter file.
:::

### Parameter Information

Click on the `Parameters` tab to examine the hiearchy of components and the parameters for each.
You can expand/collapse the Component Hierarchy tree in the left panel by clicking on the triangles or facility name in blue to the left of the equals sign ({numref}`fig:parameters:gui:parameters:empty`).
Clicking on the component in red to the right of the equals sign will show its parameters in the right panel ({numref}`fig:parameters:gui:parameters:empty`).
The selected facility in the left panel whose parameters are shown in the right panel will be highlighted via a gray background ({numref}`fig:parameters:gui:parameters:selected`).

:::{figure-md} fig:parameters:gui:parameters:empty
<img src="figs/paramgui_parameters.*" alt="Parameter Viewer screenshot of parameter information" width="100%" style="border: 1px solid #000"/>

Screenshot of `Parameters` tab of the PyLith Parameter Viewer with sample JSON parameter file before selecting a component in the left panel.
:::

:::{figure-md} fig:parameters:gui:parameters:selected
<img src="figs/paramgui_detail.*" alt="Parameter Viewer screenshot of parameter information with component selected" width="100%" style="border: 1px solid #000"/>

Screenshot of `Parameters` tab of the PyLith Parameter Viewer with sample JSON parameter file with the `z_neg` facility selected.
:::

% End of file