| Name | kim-property JSON |
| Version |
2.6.1
JSON |
| download |
| home_page | None |
| Summary | kim-property - KIM-PROPERTY utility module. |
| upload_time | 2024-03-26 02:15:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
kim-property
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# KIM-PROPERTY utility module
[](https://github.com/openkim/kim-property/actions)
[](https://codecov.io/gh/openkim/kim-property)
[](https://anaconda.org/conda-forge/kim-property)
[](https://pypi.python.org/pypi/kim-property)
[](LICENSE)
The objective is to make it as easy as possible to convert a script (for
example a [LAMMPS](https://lammps.sandia.gov/) script) that computes a
[KIM property](https://openkim.org/properties) to a KIM Test.
This utility module has 5 modes:
1- **[Create](#create)**\
Take as input the property instance ID and property definition name and
create initial property instance data structure. It checks and indicates
whether the property definition exists in [OpenKIM](https://openkim.org/).
2- **[Destroy](#destroy)**\
Delete a previously created property instance ID.
3- **[Modify](#modify)**\
Incrementally build the property instance by receiving keys with
associated arguments. It can "append" and add to a key's existing array
argument.
4- **[Remove](#remove)**\
Remove a key.
5- **[Dump](#dump)**\
Take as input the generated instance and a filename, validate each
instance against the property definition and either issues an error or
writes the instance out to file in edn format. Final validation should
make sure all keys/arguments are legal and all required keys are
provided.
To get started, you'll need to install the `kim-property` package. Please refer
to the [installation instructions](#installing-kim-property).
## Create
Creating property instances::
````py
>>> kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> kim_property_create(2, 'atomic-mass', property_inst)
'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1} {"property-id" "tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass" "instance-id" 2}]'
>>> property_inst = kim_property_create(2, 'atomic-mass', property_inst)
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
}
{
"property-id" "tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass"
"instance-id" 2
}
]
````
A property instance is stored in a subset of the KIM-EDN format as described in
[KIM Property Instances](https://openkim.org/doc/schema/properties-framework).
Each property instance must contain the `property-id` and `instance-id`.
`kim-property` utility module can create a new property instance, using a KIM
property ID. A KIM property ID is an identifier of a KIM Property Definition,
which can be,
(1) a property short name,
(2) the full unique ID of the property (including the contributor and date),
(3) a file name corresponding to a local property definition file.
Examples of each of these cases are shown below:
````py
>>> kim_property_create(1, 'atomic-mass')
>>> kim_property_create(2, 'cohesive-energy-relation-cubic-crystal')
````
````py
>>> kim_property_create(1, 'tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass')
>>> kim_property_create(2, 'tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal')
````
````py
>>> kim_property_create(1, 'new-property.edn')
>>> kim_property_create(2, '/home/mary/marys-kim-properties/dissociation-energy.edn')
````
In the last example, "new-property.edn" and
"/home/mary/marys-kim-properties/dissociation-energy.edn"
are the names of files that contain user-defined (local) property definitions.
## Destroy
Destroying property instances::
````py
>>> property_inst_obj = '[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'
>>> kim_property_destroy(property_inst_obj, 1)
'[]'
>>> property_inst_obj = '[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1} {"property-id" "tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass" "instance-id" 2}]'
>>> kim_property_destroy(property_inst_obj, 2)
'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'
````
## Modify
Modifying (setting) property instances.
Once a `kim_property_create` has been given to instantiate a property
instance, maps associated with the property's keys can be edited using the
kim_property_modify.
In using this command, the special keyword "key" should be given, followed
by the property key name and the key-value pair in the map associated with
the key that is to be set.
For example, the `cohesive-energy-relation-cubic-crystal` property definition
consists of property keys named "short-name", "species", ...
An instance of this property could be created like so::
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
}
]
````
For cases where there are multiple keys or a key receives an array of values
computed one at a time, the `kim_property_modify` can be called multiple
times and append values to a given key.
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
}
]
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
"basis-atom-coordinates" {
"source-value" [
[
0.0
0.0
0.0
]
[
0.5
0.5
0.0
]
]
}
}
]
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
"basis-atom-coordinates" {
"source-value" [
[
0.0
0.0
0.0
]
[
0.5
0.5
0.0
]
[
0.5
0.0
0.5
]
[
0.0
0.5
0.5
]
]
}
}
]
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
"basis-atom-coordinates" {
"source-value" [
[
0.0
0.0
0.0
]
[
0.5
0.5
0.0
]
[
0.5
0.0
0.5
]
[
0.0
0.5
0.5
]
]
}
"cohesive-potential-energy" {
"source-value" [
3.324
3.3576
3.36
3.355
3.326
]
"source-std-uncert-value" [
0.002
0.0001
1e-05
0.0012
0.00015
]
"source-unit" "eV"
"digits" 5
}
}
]
````
**Note:**
Variables which are introduced with a specified extent of either an empty
vector `[]` or `[1]`, are scalars.
Calling a `kim_property_modify` will update the scalars and vector values
which are already set.
For example:
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "space-group",
"source-value", "Immm")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"space-group" {
"source-value" "Immm"
}
}
]
````
Calling the `kim_property_modify` again set the scalar variable with a new
value.
````py
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "space-group",
"source-value", "P6_3/mmc")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"space-group" {
"source-value" "P6_3/mmc"
}
}
]
````
**Note:**
If the source-value key is a scalar, the values of the uncertainty and digits
keys must be scalars. Thus, calling the `kim_property_modify` with a non-scalar
key where the source-value key is a scalar fails.
**Note:**
If the source-value key's value is an array (EDN vector), the values of the
uncertainty and digits keys must be either arrays of the same extent, or
scalars in which case they are taken to apply equally to all values in the
source-value array. The keys associated with uncertainty and precision conform
to the
[ISO Guide to the Expression of Uncertainty in Measurement](https://www.iso.org/standard/50461.html)
and the
[ThermoML standard notation](https://www.degruyter.com/view/journals/ci/28/3/article-p22.xml).
The keys associated with uncertainty and precision of the
[KIM Property Instances](https://openkim.org/doc/schema/properties-framework)
are:
- source-std-uncert-value
- source-expand-uncert-value
- coverage-factor
- source-asym-std-uncert-neg
- source-asym-std-uncert-pos
- source-asym-expand-uncert-neg
- source-asym-expand-uncert-pos
- uncert-lev-of-confid
- digits
In below example, the `a`-key source-value key's value is an array, which means
the value of the `digits`-key must be either an array of the same extent, or a
scalar.
1. The value of the `digits`-key is a scalar:
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" 5
}
}
]
````
2. The value of the `digits`-key is an array of the same extent:
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "1:5", "5", "5", "5", "5", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"source-unit" "angstrom"
"digits" [
5
5
5
5
5
]
}
}
]
````
## Remove
Removing (a) key(s) from a property instance::
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5",
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5",
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5",
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> property_inst = kim_property_remove(property_inst, 1, "key", "a", "source-unit")
>>> property_inst = kim_property_remove(property_inst, 1, "key", "cohesive-potential-energy", "key", "basis-atom-coordinates")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> print(kim_edn.dumps(property_inst_obj, indent=4))
[
{
"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal"
"instance-id" 1
"short-name" {
"source-value" [
"fcc"
]
}
"species" {
"source-value" [
"Al"
"Al"
"Al"
"Al"
]
}
"a" {
"source-value" [
3.9149
4.0
4.032
4.0817
4.1602
]
"digits" 5
}
}
]
````
## Dump
First, it validates the generated instances against the property definition.
Then serializes it to a [KIM-EDN](https://github.com/openkim/kim-edn#kim-edn)
formatted stream and dumps it to a `fp` (a `.write()`-supporting file-like
object or a name string to open a file).
The validation makes sure all keys/arguments are legal and all required keys
are provided.
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5",
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5",
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5",
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> kim_property_dump(property_inst, "results.edn")
````
or
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5",
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5",
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5",
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> property_inst_obj = kim_edn.loads(property_inst)
>>> kim_property_dump(property_inst_obj, "results.edn")
````
or
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5",
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5",
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5",
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> with open("results.edn", 'w') as fp:
kim_property_dump(property_inst, fp)
````
An example with two property instances,
````py
>>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')
>>> property_inst = kim_property_modify(property_inst, 1,
"key", "short-name",
"source-value", "1", "fcc",
"key", "species",
"source-value", "1:4", "Al", "Al", "Al", "Al",
"key", "a",
"source-value", "1:5", "3.9149", "4.0000", "4.032", "4.0817", "4.1602",
"source-unit", "angstrom", "digits", "5",
"key", "basis-atom-coordinates",
"source-value", "2", "1:2", "0.5", "0.5",
"key", "basis-atom-coordinates",
"source-value", "3", "1:3", "0.5", "0.0", "0.5",
"key", "basis-atom-coordinates",
"source-value", "4", "2:3", "0.5", "0.5",
"key", "cohesive-potential-energy",
"source-value", "1:5", "3.324", "3.3576", "3.3600", "3.3550", "3.3260",
"source-std-uncert-value", "1:5", "0.002", "0.0001", "0.00001", "0.0012", "0.00015",
"source-unit", "eV",
"digits", "5")
>>> property_inst = kim_property_create(2, 'atomic-mass', property_inst)
>>> property_inst = kim_property_modify(property_inst, 2,
"key", "mass",
"source-value", "1.434e-19", "source-unit", "si",
"key", "species",
"source-value", "Al")
>>> kim_property_dump(property_inst, "results.edn")
````
## Installing kim-property
### Requirements
You need Python 3.6 or later to run `kim-property`. You can have multiple
Python versions (2.x and 3.x) installed on the same system without problems.
To install Python 3 for different Linux flavors, macOS and Windows, packages
are available at\
[https://www.python.org/getit/](https://www.python.org/getit/)
### Using pip
**pip** is the most popular tool for installing Python packages, and the one
included with modern versions of Python.
`kim-property` can be installed with `pip`:
```sh
pip install kim-property
```
**Note:**
Depending on your Python installation, you may need to use `pip3` instead of
`pip`.
```sh
pip3 install kim-property
```
Depending on your configuration, you may have to run `pip` like this:
```sh
python3 -m pip install kim-property
```
### Using pip (GIT Support)
`pip` currently supports cloning over `git`
```sh
pip install git+https://github.com/openkim/kim-property.git
```
For more information and examples, see the
[pip install](https://pip.pypa.io/en/stable/reference/pip_install/#id18) reference.
### Using conda
**conda** is the package management tool for Anaconda Python installations.
Installing `kim-property` from the `conda-forge` channel can be achieved
by adding `conda-forge` to your channels with:
```sh
conda config --add channels conda-forge
conda config --set channel_priority strict
```
Once the `conda-forge` channel has been enabled, `kim-property` can be
installed with `conda`:
```sh
conda install kim-property
```
or with `mamba`:
```sh
mamba install kim-property
```
It is possible to list all of the versions of `kim-property` available on
your platform with `conda`:
```sh
conda search kim-property --channel conda-forge
```
or with `mamba`:
```sh
mamba search kim-property --channel conda-forge
```
Alternatively, `mamba repoquery` may provide more information:
```sh
# Search all versions available on your platform:
mamba repoquery search kim-property --channel conda-forge
# List packages depending on `kim-property`:
mamba repoquery whoneeds kim-property --channel conda-forge
# List dependencies of `kim-property`:
mamba repoquery depends kim-property --channel conda-forge
```
## Copyright
Copyright (c) 2020-2024, Regents of the University of Minnesota.\
All Rights Reserved
## Contributing
Contributors:\
Yaser Afshar
Raw data
{
"_id": null,
"home_page": null,
"name": "kim-property",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Yaser Afshar <ya.afshar@gmail.com>",
"keywords": "kim-property",
"author": null,
"author_email": "Yaser Afshar <ya.afshar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/8d/4a2f7304e3d9d20ea1311b499512c4f9f8a00db30161f0c99faf828a6dcd/kim-property-2.6.1.tar.gz",
"platform": null,
"description": "# KIM-PROPERTY utility module\n\n[](https://github.com/openkim/kim-property/actions)\n[](https://codecov.io/gh/openkim/kim-property)\n[](https://anaconda.org/conda-forge/kim-property)\n[](https://pypi.python.org/pypi/kim-property)\n[](LICENSE)\n\nThe objective is to make it as easy as possible to convert a script (for\nexample a [LAMMPS](https://lammps.sandia.gov/) script) that computes a\n[KIM property](https://openkim.org/properties) to a KIM Test.\n\nThis utility module has 5 modes:\n\n1- **[Create](#create)**\\\n Take as input the property instance ID and property definition name and\n create initial property instance data structure. It checks and indicates\n whether the property definition exists in [OpenKIM](https://openkim.org/).\n\n2- **[Destroy](#destroy)**\\\n Delete a previously created property instance ID.\n\n3- **[Modify](#modify)**\\\n Incrementally build the property instance by receiving keys with\n associated arguments. It can \"append\" and add to a key's existing array\n argument.\n\n4- **[Remove](#remove)**\\\n Remove a key.\n\n5- **[Dump](#dump)**\\\n Take as input the generated instance and a filename, validate each\n instance against the property definition and either issues an error or\n writes the instance out to file in edn format. Final validation should\n make sure all keys/arguments are legal and all required keys are\n provided.\n\nTo get started, you'll need to install the `kim-property` package. Please refer\nto the [installation instructions](#installing-kim-property).\n\n## Create\n\nCreating property instances::\n\n````py\n >>> kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n '[{\"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\" \"instance-id\" 1}]'\n\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n\n >>> kim_property_create(2, 'atomic-mass', property_inst)\n '[{\"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\" \"instance-id\" 1} {\"property-id\" \"tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass\" \"instance-id\" 2}]'\n\n >>> property_inst = kim_property_create(2, 'atomic-mass', property_inst)\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n }\n {\n \"property-id\" \"tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass\"\n \"instance-id\" 2\n }\n ]\n````\n\nA property instance is stored in a subset of the KIM-EDN format as described in\n[KIM Property Instances](https://openkim.org/doc/schema/properties-framework).\nEach property instance must contain the `property-id` and `instance-id`.\n`kim-property` utility module can create a new property instance, using a KIM\nproperty ID. A KIM property ID is an identifier of a KIM Property Definition,\nwhich can be,\n(1) a property short name,\n(2) the full unique ID of the property (including the contributor and date),\n(3) a file name corresponding to a local property definition file.\n\nExamples of each of these cases are shown below:\n\n````py\n >>> kim_property_create(1, 'atomic-mass')\n >>> kim_property_create(2, 'cohesive-energy-relation-cubic-crystal')\n````\n\n````py\n >>> kim_property_create(1, 'tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass')\n >>> kim_property_create(2, 'tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal')\n````\n\n````py\n >>> kim_property_create(1, 'new-property.edn')\n >>> kim_property_create(2, '/home/mary/marys-kim-properties/dissociation-energy.edn')\n````\n\nIn the last example, \"new-property.edn\" and\n\"/home/mary/marys-kim-properties/dissociation-energy.edn\"\nare the names of files that contain user-defined (local) property definitions.\n\n## Destroy\n\nDestroying property instances::\n\n````py\n >>> property_inst_obj = '[{\"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\" \"instance-id\" 1}]'\n\n >>> kim_property_destroy(property_inst_obj, 1)\n '[]'\n\n >>> property_inst_obj = '[{\"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\" \"instance-id\" 1} {\"property-id\" \"tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass\" \"instance-id\" 2}]'\n\n >>> kim_property_destroy(property_inst_obj, 2)\n '[{\"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\" \"instance-id\" 1}]'\n````\n\n## Modify\n\nModifying (setting) property instances.\n\nOnce a `kim_property_create` has been given to instantiate a property\ninstance, maps associated with the property's keys can be edited using the\nkim_property_modify.\nIn using this command, the special keyword \"key\" should be given, followed\nby the property key name and the key-value pair in the map associated with\nthe key that is to be set.\n\nFor example, the `cohesive-energy-relation-cubic-crystal` property definition\nconsists of property keys named \"short-name\", \"species\", ...\nAn instance of this property could be created like so::\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\")\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n }\n ]\n````\n\nFor cases where there are multiple keys or a key receives an array of values\ncomputed one at a time, the `kim_property_modify` can be called multiple\ntimes and append values to a given key.\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\")\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n }\n ]\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n \"basis-atom-coordinates\" {\n \"source-value\" [\n [\n 0.0\n 0.0\n 0.0\n ]\n [\n 0.5\n 0.5\n 0.0\n ]\n ]\n }\n }\n ]\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n \"basis-atom-coordinates\" {\n \"source-value\" [\n [\n 0.0\n 0.0\n 0.0\n ]\n [\n 0.5\n 0.5\n 0.0\n ]\n [\n 0.5\n 0.0\n 0.5\n ]\n [\n 0.0\n 0.5\n 0.5\n ]\n ]\n }\n }\n ]\n\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n \"basis-atom-coordinates\" {\n \"source-value\" [\n [\n 0.0\n 0.0\n 0.0\n ]\n [\n 0.5\n 0.5\n 0.0\n ]\n [\n 0.5\n 0.0\n 0.5\n ]\n [\n 0.0\n 0.5\n 0.5\n ]\n ]\n }\n \"cohesive-potential-energy\" {\n \"source-value\" [\n 3.324\n 3.3576\n 3.36\n 3.355\n 3.326\n ]\n \"source-std-uncert-value\" [\n 0.002\n 0.0001\n 1e-05\n 0.0012\n 0.00015\n ]\n \"source-unit\" \"eV\"\n \"digits\" 5\n }\n }\n ]\n````\n\n**Note:**\n\nVariables which are introduced with a specified extent of either an empty\nvector `[]` or `[1]`, are scalars.\n\nCalling a `kim_property_modify` will update the scalars and vector values\nwhich are already set.\n\nFor example:\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"space-group\",\n \"source-value\", \"Immm\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"space-group\" {\n \"source-value\" \"Immm\"\n }\n }\n ]\n````\n\nCalling the `kim_property_modify` again set the scalar variable with a new\nvalue.\n\n````py\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"space-group\",\n \"source-value\", \"P6_3/mmc\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"space-group\" {\n \"source-value\" \"P6_3/mmc\"\n }\n }\n ]\n\n````\n\n**Note:**\n\nIf the source-value key is a scalar, the values of the uncertainty and digits\nkeys must be scalars. Thus, calling the `kim_property_modify` with a non-scalar\nkey where the source-value key is a scalar fails.\n\n**Note:**\n\nIf the source-value key's value is an array (EDN vector), the values of the\nuncertainty and digits keys must be either arrays of the same extent, or\nscalars in which case they are taken to apply equally to all values in the\nsource-value array. The keys associated with uncertainty and precision conform\nto the\n[ISO Guide to the Expression of Uncertainty in Measurement](https://www.iso.org/standard/50461.html)\nand the\n[ThermoML standard notation](https://www.degruyter.com/view/journals/ci/28/3/article-p22.xml).\n\nThe keys associated with uncertainty and precision of the\n[KIM Property Instances](https://openkim.org/doc/schema/properties-framework)\nare:\n\n- source-std-uncert-value\n- source-expand-uncert-value\n- coverage-factor\n- source-asym-std-uncert-neg\n- source-asym-std-uncert-pos\n- source-asym-expand-uncert-neg\n- source-asym-expand-uncert-pos\n- uncert-lev-of-confid\n- digits\n\nIn below example, the `a`-key source-value key's value is an array, which means\nthe value of the `digits`-key must be either an array of the same extent, or a\nscalar.\n\n1. The value of the `digits`-key is a scalar:\n\n ````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\")\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" 5\n }\n }\n ]\n ````\n\n2. The value of the `digits`-key is an array of the same extent:\n\n ````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"1:5\", \"5\", \"5\", \"5\", \"5\", \"5\")\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"source-unit\" \"angstrom\"\n \"digits\" [\n 5\n 5\n 5\n 5\n 5\n ]\n }\n }\n ]\n ````\n\n## Remove\n\nRemoving (a) key(s) from a property instance::\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\",\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n\n >>> property_inst = kim_property_remove(property_inst, 1, \"key\", \"a\", \"source-unit\")\n >>> property_inst = kim_property_remove(property_inst, 1, \"key\", \"cohesive-potential-energy\", \"key\", \"basis-atom-coordinates\")\n\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> print(kim_edn.dumps(property_inst_obj, indent=4))\n [\n {\n \"property-id\" \"tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal\"\n \"instance-id\" 1\n \"short-name\" {\n \"source-value\" [\n \"fcc\"\n ]\n }\n \"species\" {\n \"source-value\" [\n \"Al\"\n \"Al\"\n \"Al\"\n \"Al\"\n ]\n }\n \"a\" {\n \"source-value\" [\n 3.9149\n 4.0\n 4.032\n 4.0817\n 4.1602\n ]\n \"digits\" 5\n }\n }\n ]\n````\n\n## Dump\n\nFirst, it validates the generated instances against the property definition.\nThen serializes it to a [KIM-EDN](https://github.com/openkim/kim-edn#kim-edn)\nformatted stream and dumps it to a `fp` (a `.write()`-supporting file-like\nobject or a name string to open a file).\n\nThe validation makes sure all keys/arguments are legal and all required keys\nare provided.\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\",\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n >>> kim_property_dump(property_inst, \"results.edn\")\n````\n\nor\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\",\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n >>> property_inst_obj = kim_edn.loads(property_inst)\n >>> kim_property_dump(property_inst_obj, \"results.edn\")\n````\n\nor\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\",\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n >>> with open(\"results.edn\", 'w') as fp:\n kim_property_dump(property_inst, fp)\n````\n\nAn example with two property instances,\n\n````py\n >>> property_inst = kim_property_create(1, 'cohesive-energy-relation-cubic-crystal')\n >>> property_inst = kim_property_modify(property_inst, 1,\n \"key\", \"short-name\",\n \"source-value\", \"1\", \"fcc\",\n \"key\", \"species\",\n \"source-value\", \"1:4\", \"Al\", \"Al\", \"Al\", \"Al\",\n \"key\", \"a\",\n \"source-value\", \"1:5\", \"3.9149\", \"4.0000\", \"4.032\", \"4.0817\", \"4.1602\",\n \"source-unit\", \"angstrom\", \"digits\", \"5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"2\", \"1:2\", \"0.5\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"3\", \"1:3\", \"0.5\", \"0.0\", \"0.5\",\n \"key\", \"basis-atom-coordinates\",\n \"source-value\", \"4\", \"2:3\", \"0.5\", \"0.5\",\n \"key\", \"cohesive-potential-energy\",\n \"source-value\", \"1:5\", \"3.324\", \"3.3576\", \"3.3600\", \"3.3550\", \"3.3260\",\n \"source-std-uncert-value\", \"1:5\", \"0.002\", \"0.0001\", \"0.00001\", \"0.0012\", \"0.00015\",\n \"source-unit\", \"eV\",\n \"digits\", \"5\")\n >>> property_inst = kim_property_create(2, 'atomic-mass', property_inst)\n >>> property_inst = kim_property_modify(property_inst, 2,\n \"key\", \"mass\",\n \"source-value\", \"1.434e-19\", \"source-unit\", \"si\",\n \"key\", \"species\",\n \"source-value\", \"Al\")\n >>> kim_property_dump(property_inst, \"results.edn\")\n````\n\n## Installing kim-property\n\n### Requirements\n\nYou need Python 3.6 or later to run `kim-property`. You can have multiple\nPython versions (2.x and 3.x) installed on the same system without problems.\n\nTo install Python 3 for different Linux flavors, macOS and Windows, packages\nare available at\\\n[https://www.python.org/getit/](https://www.python.org/getit/)\n\n### Using pip\n\n**pip** is the most popular tool for installing Python packages, and the one\nincluded with modern versions of Python.\n\n`kim-property` can be installed with `pip`:\n\n```sh\npip install kim-property\n```\n\n**Note:**\n\nDepending on your Python installation, you may need to use `pip3` instead of\n`pip`.\n\n```sh\npip3 install kim-property\n```\n\nDepending on your configuration, you may have to run `pip` like this:\n\n```sh\npython3 -m pip install kim-property\n```\n\n### Using pip (GIT Support)\n\n`pip` currently supports cloning over `git`\n\n```sh\npip install git+https://github.com/openkim/kim-property.git\n```\n\nFor more information and examples, see the\n[pip install](https://pip.pypa.io/en/stable/reference/pip_install/#id18) reference.\n\n### Using conda\n\n**conda** is the package management tool for Anaconda Python installations.\n\nInstalling `kim-property` from the `conda-forge` channel can be achieved\nby adding `conda-forge` to your channels with:\n\n```sh\nconda config --add channels conda-forge\nconda config --set channel_priority strict\n```\n\nOnce the `conda-forge` channel has been enabled, `kim-property` can be\ninstalled with `conda`:\n\n```sh\nconda install kim-property\n```\n\nor with `mamba`:\n\n```sh\nmamba install kim-property\n```\n\nIt is possible to list all of the versions of `kim-property` available on\nyour platform with `conda`:\n\n```sh\nconda search kim-property --channel conda-forge\n```\n\nor with `mamba`:\n\n```sh\nmamba search kim-property --channel conda-forge\n```\n\nAlternatively, `mamba repoquery` may provide more information:\n\n```sh\n# Search all versions available on your platform:\nmamba repoquery search kim-property --channel conda-forge\n\n# List packages depending on `kim-property`:\nmamba repoquery whoneeds kim-property --channel conda-forge\n\n# List dependencies of `kim-property`:\nmamba repoquery depends kim-property --channel conda-forge\n```\n\n## Copyright\n\nCopyright (c) 2020-2024, Regents of the University of Minnesota.\\\nAll Rights Reserved\n\n## Contributing\n\nContributors:\\\n Yaser Afshar\n",
"bugtrack_url": null,
"license": null,
"summary": "kim-property - KIM-PROPERTY utility module.",
"version": "2.6.1",
"project_urls": {
"Homepage": "https://github.com/openkim/kim-property",
"Issues": "https://github.com/openkim/kim-property/issues"
},
"split_keywords": [
"kim-property"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ffcd1571ad29bbafd0121d21dcab2306cc1dae39753b2a952aded1a6d6f93355",
"md5": "af05006258064e7cb3fe533756a6b1f1",
"sha256": "eccc20a4006e54c979b98db0fe4eed57913513ebe421b39448f26d888f30c389"
},
"downloads": -1,
"filename": "kim_property-2.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af05006258064e7cb3fe533756a6b1f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 67406,
"upload_time": "2024-03-26T02:15:55",
"upload_time_iso_8601": "2024-03-26T02:15:55.774155Z",
"url": "https://files.pythonhosted.org/packages/ff/cd/1571ad29bbafd0121d21dcab2306cc1dae39753b2a952aded1a6d6f93355/kim_property-2.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b18d4a2f7304e3d9d20ea1311b499512c4f9f8a00db30161f0c99faf828a6dcd",
"md5": "a5b8de1c735d884b46639b05ef7fd99c",
"sha256": "45b9265cd3d1b66f5dba230ae7e2862bd0ba379e34aee51b4780a00ff5d897b9"
},
"downloads": -1,
"filename": "kim-property-2.6.1.tar.gz",
"has_sig": false,
"md5_digest": "a5b8de1c735d884b46639b05ef7fd99c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 65983,
"upload_time": "2024-03-26T02:15:57",
"upload_time_iso_8601": "2024-03-26T02:15:57.190095Z",
"url": "https://files.pythonhosted.org/packages/b1/8d/4a2f7304e3d9d20ea1311b499512c4f9f8a00db30161f0c99faf828a6dcd/kim-property-2.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-26 02:15:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openkim",
"github_project": "kim-property",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kim-property"
}
