{ "info": { "author": "Gideon Mueller", "author_email": "g.mueller@fz-juelich.de", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: C", "Programming Language :: C++", "Programming Language :: Python", "Topic :: Scientific/Engineering", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "OVF Parser Library\n=================================\n**Simple API for powerful OOMMF Vector Field file parsing**
\n\n[OVF format specification](#specification)\n\n[![Build Status](https://travis-ci.org/spirit-code/ovf.svg?branch=master)](https://travis-ci.org/spirit-code/ovf)\n[![Build status](https://ci.appveyor.com/api/projects/status/ur0cq1tykfndlj06/branch/master?svg=true)](https://ci.appveyor.com/project/GPMueller/ovf)\n\n**[Python package](https://pypi.org/project/ovf/):** [![PyPI version](https://badge.fury.io/py/ovf.svg)](https://badge.fury.io/py/ovf)\n\n| Library Coverage | Python Bindings Coverage |\n| :--------------: | :----------------------: |\n| [![Library Coverage Status](https://codecov.io/gh/spirit-code/ovf/branch/master/graph/badge.svg)](https://codecov.io/gh/spirit-code/ovf/branch/master) | [![Python Bindings Coverage Status](https://coveralls.io/repos/github/spirit-code/ovf/badge.svg?branch=master)](https://coveralls.io/github/spirit-code/ovf?branch=master)|\n\nHow to use\n---------------------------------\n\nFor usage examples, take a look into the test folders: [test](https://github.com/spirit-code/ovf/tree/master/test), [python/test](https://github.com/spirit-code/ovf/tree/master/python/test) or [fortran/test](https://github.com/spirit-code/ovf/tree/master/fortran/test).\n\nExcept for opening a file or initializing a segment, all functions return status codes\n(generally `OVF_OK`, `OVF_INVALID` or `OVF_ERROR`).\nWhen the return code is not `OVF_OK`, you can take a look into the latest message,\nwhich should tell you what the problem was\n(`const char * ovf_latest_message(struct ovf_file *)` in the C API).\n\nIn C/C++ and Fortran, before writing a segment, make sure the `ovf_segment` you pass in is\ninitialized, i.e. you already called either `ovf_read_segment_header` or `ovf_segment_create`.\n\n### C/C++\n\nOpening and closing:\n\n- `struct ovf_file *myfile = ovf_open(\"myfilename.ovf\")` to open a file\n- `myfile->found` to check if the file exists on disk\n- `myfile->is_ovf` to check if the file contains an OVF header\n- `myfile->n_segments` to check the number of segments the file should contain\n- `ovf_close(myfile);` to close the file and free resources\n\nReading from a file:\n\n- `struct ovf_segment *segment = ovf_segment_create()` to initialize a new segment and get the pointer\n- `ovf_read_segment_header(myfile, index, segment)` to read the header into the segment struct\n- create float data array of appropriate size...\n- `ovf_read_segment_data_4(myfile, index, segment, data)` to read the segment data into your float array\n- setting `segment->N` before reading allows partial reading of large data segments\n\nWriting and appending to a file:\n\n- `struct ovf_segment *segment = ovf_segment_create()` to initialize a new segment and get the pointer\n- `segment->n_cells[0] = ...` etc to set data dimensions, title and description, etc.\n- `ovf_write_segment_4(myfile, segment, data, OVF_FORMAT_TEXT)` to write a file containing the segment header and data\n- `ovf_append_segment_4(myfile, segment, data, OVF_FORMAT_TEXT)` to append the segment header and data to the file\n\n### Python\n\nTo install the *ovf python package*, either build and install from source\nor simply use\n\n pip install ovf\n\nTo use `ovf` from Python, e.g.\n\n```Python\nfrom ovf import ovf\nimport numpy as np\n\ndata = np.zeros((2, 2, 1, 3), dtype='f')\ndata[0,1,0,:] = [3.0, 2.0, 1.0]\n\nwith ovf.ovf_file(\"out.ovf\") as ovf_file:\n\n # Write one segment\n segment = ovf.ovf_segment(n_cells=[2,2,1])\n if ovf_file.write_segment(segment, data) != -1:\n print(\"write_segment failed: \", ovf_file.get_latest_message())\n\n # Add a second segment to the same file\n data[0,1,0,:] = [4.0, 5.0, 6.0]\n if ovf_file.append_segment(segment, data) != -1:\n print(\"append_segment failed: \", ovf_file.get_latest_message())\n```\n\n### Fortran\n\nThe Fortran bindings are written in object-oriented style for ease of use.\nWriting a file, for example:\n\n```fortran\ntype(ovf_file) :: file\ntype(ovf_segment) :: segment\ninteger :: success\nreal(kind=4), allocatable :: array_4(:,:)\nreal(kind=8), allocatable :: array_8(:,:)\n\n! Initialize segment\ncall segment%initialize()\n\n! Write a file\ncall file%open_file(\"fortran/test/testfile_f.ovf\")\nsegment%N_Cells = [ 2, 2, 1 ]\nsegment%N = product(segment%N_Cells)\n\nallocate( array_4(3, segment%N) )\narray_4 = 0\narray_4(:,1) = [ 6.0, 7.0, 8.0 ]\narray_4(:,2) = [ 5.0, 4.0, 3.0 ]\n\nsuccess = file%write_segment(segment, array_4, OVF_FORMAT_TEXT)\nif ( success == OVF_OK) then\n write (*,*) \"test write_segment succeeded.\"\n ! write (*,*) \"n_cells = \", segment%N_Cells\n ! write (*,*) \"n_total = \", segment%N\nelse\n write (*,*) \"test write_segment did not work. Message: \", file%latest_message\n STOP 1\nendif\n```\n\nFor more information on how to generate modern Fortran bindings,\nsee also https://github.com/MRedies/Interfacing-Fortran\n\n\nHow to embed it into your project\n---------------------------------\n\nIf you are using CMake, it is as simple as cloning this into a subdirectory,\ne.g. `thirdparty/ovf` and using it with `add_subdirectory`:\n\n```\nadd_subdirectory( ${PROJECT_SOURCE_DIR}/thirdparty/ovf )\nset( OVF_INCLUDE_DIRS ${PROJECT_SOURCE_DIR}/thirdparty/ovf/include )\ntarget_include_directories( myproject PRIVATE ${OVF_INCLUDE_DIRS} )\ntarget_link_libraries( myproject PUBLIC ${OVF_LIBRARIES_STATIC} )\n```\n\nIf you're not using CMake, you may need to put in some manual work.\n\n\nBuild\n---------------------------------\n\n### On Unix systems\n\nUsually:\n```\nmkdir build\ncd build\ncmake ..\nmake\n```\n\n### On Windows\n\nOne possibility:\n- open the folder in the CMake GUI\n- generate the VS project\n- open the resulting project in VS and build it\n\n### CMake Options\n\nThe following options are `ON` by default.\nIf you want to switch them off, just pass `-D