.. _mpas_to_xdmf: ====================== MPAS to XDMF Converter ====================== The MPAS to XDMF Converter is a tool designed to convert MPAS output files into XDMF + HDF5 format for visualization in tools like ParaView. This converter simplifies the process of working with MPAS data by providing a format that is more compatible with common visualization software. Overview ======== The MPAS to XDMF Converter allows users to transform MPAS NetCDF files into XDMF + HDF5 format, which is widely supported by visualization tools like ParaView. The tool supports slicing along extra dimensions, combining mesh and time series data, and selecting specific variables for conversion. Usage ===== The converter can be used via its command-line interface ``mpas_to_xdmf`` or as a Python library. Command-Line Arguments ---------------------- The following arguments are supported: - ``-m, --mesh``: Path to the MPAS mesh file (required). - ``-t, --time-series``: Wildcard or list of time series files (optional). - ``-v, --variables``: List of variables to convert. Special keys include: - ``allOnCells``: Variables with dimension ``nCells``. - ``allOnEdges``: Variables with dimension ``nEdges``. - ``allOnVertices``: Variables with dimension ``nVertices``. - ``-o, --output-dir``: Directory to save XDMF files (required). - ``-x, --xtime``: Name of the variable containing time information (optional). - ``-d, --dim-list``: List of dimensions and indices to slice (e.g., ``nVertLevels=0:10:2``). Examples -------- Command-Line Examples ~~~~~~~~~~~~~~~~~~~~~ Convert a mesh file and time series files, selecting specific variables: .. code-block:: bash mpas_to_xdmf -m mesh.nc -t time_series.*.nc -v temperature,salinity -o output_dir Convert all variables on cells, slicing along ``nVertLevels``: .. code-block:: bash mpas_to_xdmf -m mesh.nc -t time_series.*.nc -v allOnCells -o output_dir -d nVertLevels=0:5 Python Examples ~~~~~~~~~~~~~~~ Use the package programmatically to load data and convert it to XDMF: .. code-block:: python from mpas_tools.viz.mpas_to_xdmf.mpas_to_xdmf import MpasToXdmf # Initialize the converter converter = MpasToXdmf() # Load the mesh and time series files converter.load( mesh_filename="mesh.nc", time_series_filenames=["time_series.0001.nc", "time_series.0002.nc"], variables=["temperature", "salinity"], xtime_var="xtime" ) # Convert to XDMF format converter.convert_to_xdmf(out_dir="output_dir") Slice along extra dimensions and convert: .. code-block:: python from mpas_tools.viz.mpas_to_xdmf.mpas_to_xdmf import MpasToXdmf # Initialize the converter converter = MpasToXdmf() # Load the mesh and time series files converter.load( mesh_filename="mesh.nc", time_series_filenames="time_series.*.nc", variables=["allOnCells"], xtime_var="xtime" ) # Define extra dimensions to slice extra_dims = {"nVertLevels": [0, 1, 2, 3, 4]} # Convert to XDMF format with slicing converter.convert_to_xdmf(out_dir="output_dir", extra_dims=extra_dims) Input and Output ================ The tool supports the following input and output formats: Input Files ----------- - **Mesh File**: A NetCDF file containing the MPAS mesh (e.g., ``mesh.nc``). This file is also used for the variables to extract if alternate data files (e.g. a time series) are not provided. - **Time Series Files**: Optional NetCDF file(s) containing the data to be extracted, often a time series (e.g., ``time_series.*.nc``). Output Files ------------ - **XDMF Files**: Metadata files describing the structure of the data. - **HDF5 Files**: Binary files containing the actual data. The output files are saved in the specified directory, with separate files for cell-centered, edge-centered, and vertex-centered data. Features ======== The MPAS to XDMF Converter includes several basic features: - **Slicing Extra Dimensions**: Users can slice along extra dimensions (e.g., ``nVertLevels``) by specifying indices or ranges. - **Combining Mesh and Time Series Data**: The tool will merge mesh and time series files into a single dataset for conversion. - **Selective Variable Conversion**: Users can choose specific variables or groups of variables (e.g., ``allOnCells``) for conversion. Opening Files in ParaView ========================= Once the conversion is complete, you can open the generated XDMF files in ParaView for visualization. Follow these steps: 1. **Open the XDMF File**: In ParaView, open the ``.xdmf`` file, not the ``.h5`` file. The ``.xdmf`` file contains the metadata that links to the data stored in the ``.h5`` file. 2. **Choose the Correct Reader**: When opening the ``.xdmf`` file, ParaView will prompt you to select one of three readers: - **Xdmf3 Reader S**: This reader is optimized for static datasets without time information. It is not suitable for time-varying MPAS data. - **Xdmf3 Reader T**: This reader is designed for time-varying datasets and is the preferred choice for MPAS data converted with this tool. - **XDMF Reader**: This is an older reader that may not fully support modern XDMF features and should generally be avoided. **Recommendation**: Always select the **Xdmf3 Reader T** when prompted. This ensures that time-varying data is handled correctly, allowing you to explore the temporal evolution of your dataset in ParaView. 3. **Select Fields to Import**: After choosing the reader, ParaView will display a list of fields available for import. Uncheck any fields you do not wish to view, then click the **Apply** button to load the selected fields. 4. **Visualize the Data**: After selecting the correct reader and fields, the dataset will load into ParaView. You can then use ParaView's tools to visualize and analyze the data. By following these steps, you can ensure that your MPAS data is correctly interpreted and visualized in ParaView. References ========== - `ParaView Documentation `_ - `XDMF Format Specification `_ - `xarray Documentation `_