{"id":15020467,"url":"https://github.com/prs513rosewood/uvw","last_synced_at":"2025-10-26T00:31:12.251Z","repository":{"id":48214027,"uuid":"179702213","full_name":"prs513rosewood/uvw","owner":"prs513rosewood","description":"Python package to write numpy arrays to VTK XML files","archived":false,"fork":false,"pushed_at":"2024-09-13T13:40:53.000Z","size":274,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-31T13:05:36.783Z","etag":null,"topics":["mpi4py","numpy","python3","vtk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prs513rosewood.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-05T14:55:24.000Z","updated_at":"2024-09-13T13:40:56.000Z","dependencies_parsed_at":"2023-11-23T10:25:07.884Z","dependency_job_id":"1d5a60e1-f8c8-4142-af8b-5571b3c3fb3d","html_url":"https://github.com/prs513rosewood/uvw","commit_stats":{"total_commits":143,"total_committers":3,"mean_commits":"47.666666666666664","dds":0.4055944055944056,"last_synced_commit":"6a9d3ed2baa96a157ec8902b40f83b7e698888eb"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prs513rosewood%2Fuvw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prs513rosewood%2Fuvw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prs513rosewood%2Fuvw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prs513rosewood%2Fuvw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prs513rosewood","download_url":"https://codeload.github.com/prs513rosewood/uvw/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238235629,"owners_count":19438725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mpi4py","numpy","python3","vtk"],"created_at":"2024-09-24T19:55:06.975Z","updated_at":"2025-10-26T00:31:11.553Z","avatar_url":"https://github.com/prs513rosewood.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"UVW - Universal VTK Writer\n==========================\n[![Build Status](https://github.com/prs513rosewood/uvw/actions/workflows/tests.yml/badge.svg)](https://github.com/prs513rosewood/uvw/actions/workflows/tests.yml)\n[![Coverage\nStatus](https://coveralls.io/repos/github/prs513rosewood/uvw/badge.svg?branch=master)](https://coveralls.io/github/prs513rosewood/uvw?branch=master)\n[![PyPI Version](https://img.shields.io/pypi/v/uvw.svg)](https://pypi.org/project/uvw/)\n\nUVW is a small utility library to write [XML VTK\nfiles](https://kitware.github.io/vtk-examples/site/VTKFileFormats/#xml-file-formats)\nfrom data contained in Numpy arrays. It handles fully-fledged `ndarrays` defined\nover {1, 2, 3}-d domains, with arbitrary number of components. There are no\nconstraints on the particular order of components, although copy of data can be\navoided if the array is Fortran contiguous, as VTK files are written in Fortran\norder. UVW supports multi-process writing of VTK files, so that it can be used\nin an MPI environment.\n\n## Getting Started\n\nHere is how to install and use `uvw`.\n\n### Prerequisites\n\n* Python 3. It may work with python 2, but it hasn't been tested.\n* [Numpy](http://www.numpy.org/). This code has been tested with Numpy version\n  1.14.3.\n* (Optional) [mpi4py](https://mpi4py.readthedocs.io/en/stable/) only if you wish to use the\n  parallel classes of UVW (i.e. the submodule `uvw.parallel`)\n\n### Installing\n\nThis library can be installed with `pip`:\n\n```\npip install --user uvw\n```\n\nIf you want to activate parallel capabilities, run:\n\n```\npip install --user uvw[mpi]\n```\n\nwhich will automatically pull `mpi4py` as a dependency.\n\n### Writing Numpy arrays\n\nAs a first example, let us write a multi-component numpy array into a\nrectilinear grid:\n\n```python\nimport numpy as np\nfrom uvw import RectilinearGrid, DataArray\n\n# Creating coordinates\nx = np.linspace(-0.5, 0.5, 10)\ny = np.linspace(-0.5, 0.5, 20)\nz = np.linspace(-0.9, 0.9, 30)\n\n# Creating the file (with possible data compression)\ngrid = RectilinearGrid('grid.vtr', (x, y, z), compression=True)\n\n# A centered ball\nx, y, z = np.meshgrid(x, y, z, indexing='ij')\nr = np.sqrt(x**2 + y**2 + z**2)\nball = r \u003c 0.3\n\n# Some multi-component multi-dimensional data\ndata = np.zeros([10, 20, 30, 3, 3])\ndata[ball, ...] = np.array([[0, 1, 0],\n                            [1, 0, 0],\n                            [0, 1, 1]])\n\n# Some cell data\ncell_data = np.zeros([9, 19, 29])\ncell_data[0::2, 0::2, 0::2] = 1\n\n# Adding the point data (see help(DataArray) for more info)\ngrid.addPointData(DataArray(data, range(3), 'ball'))\n# Adding the cell data\ngrid.addCellData(DataArray(cell_data, range(3), 'checkers'))\ngrid.write()\n```\n\nUVW also supports writing data on 2D and 1D physical domains, for example:\n\n```python\nimport sys\nimport numpy as np\nfrom uvw import RectilinearGrid, DataArray\n\n# Creating coordinates\nx = np.linspace(-0.5, 0.5, 10)\ny = np.linspace(-0.5, 0.5, 20)\n\n# A centered disk\nxx, yy = np.meshgrid(x, y, indexing='ij')\nr = np.sqrt(xx**2 + yy**2)\nR = 0.3\ndisk = r \u003c R\n\ndata = np.zeros([10, 20])\ndata[disk] = np.sqrt(1-(r[disk]/R)**2)\n\n# File object can be used as a context manager\n# and you can write to stdout!\nwith RectilinearGrid(sys.stdout, (x, y)) as grid:\n  grid.addPointData(DataArray(data, range(2), 'data'))\n```\n\n## Writing in parallel with `mpi4py`\n\nThe classes contained in the `uvw.parallel` submodule support multi-process\nwriting using `mpi4py`. Here is a code example:\n\n```python\nimport numpy as np\n\nfrom mpi4py import MPI\n\nfrom uvw.parallel import PRectilinearGrid\nfrom uvw import DataArray\n\ncomm = MPI.COMM_WORLD\nrank = comm.Get_rank()\n\nN = 20\n\n# Domain bounds per rank\nbounds = [\n    {'x': (-2, 0), 'y': (-2, 0)},\n    {'x': (-2, 0), 'y': (0,  2)},\n    {'x': (0,  2), 'y': (-2, 2)},\n]\n\n# Domain sizes per rank\nsizes = [\n    {'x': N, 'y': N},\n    {'x': N, 'y': N},\n    {'x': N, 'y': 2*N-1},  # account for overlap\n]\n\n# Size offsets per rank\noffsets = [\n    [0, 0],\n    [0, N],\n    [N, 0],\n]\n\nx = np.linspace(*bounds[rank]['x'], sizes[rank]['x'])\ny = np.linspace(*bounds[rank]['y'], sizes[rank]['y'])\n\nxx, yy = np.meshgrid(x, y, indexing='ij', sparse=True)\nr = np.sqrt(xx**2 + yy**2)\ndata = np.exp(-r**2)\n\n# Indicating rank info with a cell array\nproc = np.ones((x.size-1, y.size-1)) * rank\n\nwith PRectilinearGrid('pgrid.pvtr', (x, y), offsets[rank]) as rect:\n    rect.addPointData(DataArray(data, range(2), 'gaussian'))\n    rect.addCellData(DataArray(proc, range(2), 'proc'))\n```\n\nAs you can see, using `PRectilinearGrid` feels just like using\n`RectilinearGrid`, except that you need to supply the position of the local grid\nin the global grid numbering (the `offsets[rank]` in the above example). Note\nthat RecilinearGrid VTK files need an overlap in point data, hence why the\nglobal grid size ends up being `(2*N-1, 2*N-1)`. If you forget that overlap,\nParaview (or another VTK-based software) may complain that some parts in the\nglobal grid (aka \"extents\" in VTK) are missing data.\n\n## Writing unstructured data\n\nUVW supports VTK's UnstructuredGrid, where the geometry is given with a list of\nnodes and a connectivity. The `UnstructuredGrid` class expects connectivity to\nbe a dictionnary enumerating the different connectivity types and the cells\nassociated to each type. For example:\n\n```python\nimport numpy as np\n\nfrom uvw import UnstructuredGrid\nfrom uvw.unstructured import CellType\n\nnodes = np.array([\n    [0, 0, 0],\n    [1, 0, 0],\n    [1, 1, 0],\n    [0, 1, 0],\n    [2, 0, 0],\n    [0, 2, 0],\n    [1, 2, 0],\n])\n\nconnectivity = {\n    CellType.QUAD: np.array([\n        [0, 1, 2, 3], [2, 6, 5, 3],\n    ]),\n    5: np.array([[4, 2, 1]]),\n}\n\nf = UnstructuredGrid('ugrid.vtu', nodes, connectivity)\nf.write()\n```\n\nAs you can see, cell types can be specified with the `unstructured.CellType`\nenumeration or with the underlying integer value (see\n[VTKFileFormats](https://kitware.github.io/vtk-examples/site/VTKFileFormats/)\nfor more info). `UnstructuredGrid` performs a sanity check of the connectivity\nto see if the number of nodes matches the cell type.\n\nIf you work with large amounts of unstructured data, consider checking out\n[meshio](https://github.com/nschloe/meshio) which provides many different\nread/write capabilities for various unstructured formats, some of which are\nsupported by VTK and are better than VTK's simple XML format.\n\n## List of features\n\nHere is a list of what is available in UVW:\n\n### VTK file formats\n\n- Image data (`.vti`)\n- Rectilinear grid (`.vtr`)\n- Structured grid (`.vts`)\n- Unstructured grid (`.vtu`)\n- Parallel Rectilinear grid (`.pvtr`)\n- Parallel Image data (`.pvti`)\n- ParaView Data (`.pvd`)\n\n### Data representation\n\n- ASCII\n- Base64 (raw and compressed: the `compression` argument of file constructors\n  can be `True`, `False`, or an integer in `[-1, 9]` for compression levels)\n\nNote that raw binary data, while more space efficient and supported by VTK,\nis not valid XML, and therefore not supported by UVW, which uses minidom for XML\nwriting.\n\n### PyEVTK high-level API implementation\n\nTo facilitate transition from\n[PyEVTK](https://github.com/pyscience-projects/pyevtk), UVW implements a part of\nits API, without imposing restrictions on data (such as the number of components\nper array) and allowing data compression. Simply replace `import pyevtk.hl` by\n`import uvw.dropin.hl`. To enable compression, provide `compression=True` to any\nof the functions in `uvw.dropin.hl`. *Note*: the drop-in is not automatically\ntested, do not hesitate to report problems.\n\n### Planned developments\n\nHere is a list of future developments:\n\n- [x] Image data\n- [x] Unstructured grid\n- [x] Structured grid\n- [x] Parallel writing (`mpi4py`-enabled `PRectilinearGrid` and `PImageData`\n      *are now available!*)\n- [ ] Benchmarking + performance comparison with\n      [pyevtk](https://github.com/pyscience-projects/pyevtk)\n\n\n## Developing\n\nThese instructions will get you a copy of the project up and running on your\nlocal machine for development and testing purposes.\n\n### Git repository\n\nFirst clone the git repository:\n\n```\ngit clone https://github.com/prs513rosewood/uvw.git\n```\n\nThen you can use pip in development mode (possibly in\n[virtualenv](https://virtualenv.pypa.io/en/stable/)):\n\n```\npip install --user -e .[mpi,tests]\n```\nInstalling with the `tests` extra pulls `vtk` as a dependency. This is because\nreading files with VTK in tests is the most reliable way to check file\nintegrity.\n\n## Running the tests\n\nThe tests can be run using [pytest](https://docs.pytest.org/en/latest/):\n\n```\npytest\n# or for tests with mpi\nmpiexec -n 2 pytest --with-mpi\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE.md file for\ndetails.\n\n## Acknowledgments\n\n* [@PurpleBooth](https://github.com/PurpleBooth)'s\n  [README-Template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprs513rosewood%2Fuvw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprs513rosewood%2Fuvw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprs513rosewood%2Fuvw/lists"}