Route providing computed grain boundary data for a material following the methodology discussed by [Hui *et al.*](https://doi.org/10.1016/j.actamat.2019.12.030) Note that grain boundary data has not been calculated for all materials in the Materials Project database. See the `GrainBoundaryDoc` schema for a full list of fields returned by this route.
openapi: 3.1.0
info:
title: Materials Project Defect Tasks Materials Grain Boundaries API
description: "\nThe Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.\n\nThis allows for analysis, development of automated tools, machine learning, downloading personal copies of the Materials Project database and more on a large scale.\n\nThe API is offered with the hopes of making Materials Project data more useful to you. We want you to use our data! As such, the API is offered free-of-charge and we support several tools to help you get started.\n\n## API Key\nTo make any request to the Materials Project API, you must use an API key. Your API key is generated for you automatically upon registering with the Materials Project website and is synced with the email you used to register.\n\nRemember to keep your API key safe and to not share it with anyone you do not trust.\n\nIf you are logged in, you can always access your API key from this page or from your [dashboard](https://next-gen.materialsproject.org/dashboard).\n\nIf you intend heavy API usage, you can give us a heads up by sending a message to <heavy.api.use@materialsproject.org>. With the exception of retrieving charge densities, this is not required, but may help us if we see unusual load on our servers.\n\n## Accessing Data\nTo use the API, you have three options:\n\n1. You can use our first-party supported Python client. This is the recommend route. The `mp-api` package containing the client is pip installable.\n\n ```\n pip install mp-api\n ```\n\n The `MPRester` client can be accessed by importing from it. This will ultimately replace the legacy `MPRester` available in pymatgen.\n\n For more details on how to use this, including code examples, please see <https://next-gen.materialsproject.org/api>.\n\n2. You can demo the API interactively on this documentation page. Click the \"Authorize\" button, paste in your API key, and then click the appropriate section to try out a query.\n\n3. Since this is a REST API, and offers a fully-compliant OpenAPI specification, it's possible to use the API with many libraries in many languages and environments, including JavaScript, MATLAB, Mathematica, etc. However, we do not offer first-party support for explaining how to do this, and you will have to follow the specification yourself.\n\n"
version: 0.86.4rc5.dev1+g77c2c1315
x-logo:
url: https://raw.githubusercontent.com/materialsproject/emmet/master/emmet-api/emmet/api/core/assets/mp_logo_small.png
security:
- ApiKeyAuth: []
tags:
- name: Materials Grain Boundaries
description: Route providing computed grain boundary data for a material following the methodology discussed by [Hui *et al.*](https://doi.org/10.1016/j.actamat.2019.12.030) Note that grain boundary data has not been calculated for all materials in the Materials Project database. See the `GrainBoundaryDoc` schema for a full list of fields returned by this route.
paths:
/materials/grain_boundaries/:
get:
tags:
- Materials Grain Boundaries
summary: Get GrainBoundaryDoc documents
operationId: search_materials_grain_boundaries__get
parameters:
- name: material_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of material_id values to query on
title: Material Ids
description: Comma-separated list of material_id values to query on
- name: task_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of Materials Project IDs to query on.
title: Task Ids
description: Comma-separated list of Materials Project IDs to query on.
- name: sigma_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of sigma
title: Sigma Max
description: Query for maximum value of sigma
- name: sigma_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of sigma
title: Sigma Min
description: Query for minimum value of sigma
- name: sigma
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Value of sigma.
title: Sigma
description: Value of sigma.
- name: sigma_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for sigma being not equal to an exact value
title: Sigma Not Eq
description: Query for sigma being not equal to an exact value
- name: sigma_eq_any
in: query
required: false
schema:
type: string
description: Query for sigma being any of these values. Provide a comma separated list.
title: Sigma Eq Any
description: Query for sigma being any of these values. Provide a comma separated list.
- name: sigma_neq_any
in: query
required: false
schema:
type: string
description: Query for sigma being not any of these values. Provide a comma separated list.
title: Sigma Neq Any
description: Query for sigma being not any of these values. Provide a comma separated list.
- name: rotation_angle_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of rotation_angle
title: Rotation Angle Max
description: Query for maximum value of rotation_angle
- name: rotation_angle_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of rotation_angle
title: Rotation Angle Min
description: Query for minimum value of rotation_angle
- name: gb_energy_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of gb_energy
title: Gb Energy Max
description: Query for maximum value of gb_energy
- name: gb_energy_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of gb_energy
title: Gb Energy Min
description: Query for minimum value of gb_energy
- name: w_sep_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of w_sep
title: W Sep Max
description: Query for maximum value of w_sep
- name: w_sep_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of w_sep
title: W Sep Min
description: Query for minimum value of w_sep
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Grain boundary type.
title: Type
description: Grain boundary type.
- name: chemsys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Dash-delimited string of elements in the material.
title: Chemsys
description: Dash-delimited string of elements in the material.
- name: pretty_formula
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Formula of the material.
title: Pretty Formula
description: Formula of the material.
- name: gb_plane
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Miller index of the grain boundary plane as comma delimitd integers.
title: Gb Plane
description: Miller index of the grain boundary plane as comma delimitd integers.
- name: rotation_axis
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Miller index of the rotation axis as comma delimitd integers.
title: Rotation Axis
description: Miller index of the rotation axis as comma delimitd integers.
- name: _page
in: query
required: false
schema:
type: integer
description: Page number to request (takes precedent over _limit and _skip).
title: ' Page'
description: Page number to request (takes precedent over _limit and _skip).
- name: _per_page
in: query
required: false
schema:
type: integer
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
default: 100
title: ' Per Page'
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
- name: _skip
in: query
required: false
schema:
type: integer
description: Number of entries to skip in the search.
default: 0
title: ' Skip'
description: Number of entries to skip in the search.
- name: _limit
in: query
required: false
schema:
type: integer
description: Max number of entries to return in a single query. Limited to 1000.
default: 100
title: ' Limit'
description: Max number of entries to return in a single query. Limited to 1000.
- name: _fields
in: query
required: false
schema:
type: string
description: 'Fields to project from GrainBoundaryDoc as a list of comma separated strings. Fields include: `material_id` `sigma` `type` `rotation_axis` `gb_plane` `rotation_angle` `gb_energy` `initial_structure` `final_structure` `pretty_formula` `w_sep` `structure` `chemsys` `last_updated`'
title: ' Fields'
description: 'Fields to project from GrainBoundaryDoc as a list of comma separated strings. Fields include: `material_id` `sigma` `type` `rotation_axis` `gb_plane` `rotation_angle` `gb_energy` `initial_structure` `final_structure` `pretty_formula` `w_sep` `structure` `chemsys` `last_updated`'
- name: _all_fields
in: query
required: false
schema:
type: boolean
description: Include all fields.
default: false
title: ' All Fields'
description: Include all fields.
responses:
'200':
description: Search for a GrainBoundaryDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_GrainBoundaryDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TypedSiteProperitesDict:
properties:
magmom:
anyOf:
- type: number
- type: 'null'
title: Magmom
charge:
anyOf:
- type: number
- type: 'null'
title: Charge
velocities:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Velocities
selective_dynamics:
anyOf:
- prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Selective Dynamics
coordination_no:
anyOf:
- type: integer
- type: 'null'
title: Coordination No
forces:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Forces
type: object
title: TypedSiteProperitesDict
TypedSiteDict:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
name:
anyOf:
- type: string
- type: 'null'
title: Name
properties:
anyOf:
- $ref: '#/components/schemas/TypedSiteProperitesDict'
- type: 'null'
species:
anyOf:
- items:
$ref: '#/components/schemas/TypedSpeciesDict'
type: array
- type: 'null'
title: Species
abc:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Abc
xyz:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Xyz
type: object
title: TypedSiteDict
Response_GrainBoundaryDoc_:
properties:
data:
anyOf:
- items:
$ref: '#/components/schemas/GrainBoundaryDoc'
type: array
- type: 'null'
title: Data
description: List of returned data
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
description: Any errors on processing this query
meta:
anyOf:
- $ref: '#/components/schemas/Meta'
- type: 'null'
description: Extra information for the query
type: object
title: Response[GrainBoundaryDoc]
TypedLatticeDict:
properties:
matrix:
items:
items:
type: number
type: array
type: array
title: Matrix
pbc:
anyOf:
- prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Pbc
a:
type: number
title: A
b:
type: number
title: B
c:
type: number
title: C
alpha:
type: number
title: Alpha
beta:
type: number
title: Beta
gamma:
type: number
title: Gamma
volume:
type: number
title: Volume
type: object
required:
- matrix
- a
- b
- c
- alpha
- beta
- gamma
- volume
title: TypedLatticeDict
TypedAggregateProperitesDict:
properties:
magmom:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Magmom
charge:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Charge
velocities:
anyOf:
- items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Velocities
selective_dynamics:
anyOf:
- items:
prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Selective Dynamics
type: object
title: TypedAggregateProperitesDict
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
GrainBoundaryDoc:
properties:
material_id:
anyOf:
- type: string
- type: 'null'
title: Material Id
description: 'The Materials Project ID of the material. This comes in the form: mp-******.'
sigma:
anyOf:
- type: integer
- type: 'null'
title: Sigma
description: Sigma value of the boundary.
type:
anyOf:
- type: string
- type: 'null'
title: Type
description: Grain boundary type.
rotation_axis:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Rotation Axis
description: Rotation axis.
gb_plane:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Gb Plane
description: Grain boundary plane.
rotation_angle:
anyOf:
- type: number
- type: 'null'
title: Rotation Angle
description: Rotation angle in degrees.
gb_energy:
anyOf:
- type: number
- type: 'null'
title: Gb Energy
description: Grain boundary energy in J/m^2.
initial_structure:
anyOf:
- $ref: '#/components/schemas/TypedGrainBoundaryDict'
- type: 'null'
title: Initial Structure
description: Initial grain boundary structure.
final_structure:
anyOf:
- $ref: '#/components/schemas/TypedGrainBoundaryDict'
- type: 'null'
title: Final Structure
description: Final grain boundary structure.
pretty_formula:
anyOf:
- type: string
- type: 'null'
title: Pretty Formula
description: Reduced formula of the material.
w_sep:
anyOf:
- type: number
- type: 'null'
title: W Sep
description: Work of separation in J/m^2.
structure:
anyOf:
- $ref: '#/components/schemas/TypedStructureDict'
- type: 'null'
title: Structure
description: Structure.
chemsys:
anyOf:
- type: string
- type: 'null'
title: Chemsys
description: Dash-delimited string of elements in the material.
last_updated:
type: string
format: date-time
title: Last Updated
description: Timestamp for the most recent calculation for this Material document.
type: object
title: GrainBoundaryDoc
description: Grain boundary energies, work of separation...
TypedStructureDict:
properties:
'@module':
type: string
title: '@Module'
'@class':
type: string
title: '@Class'
charge:
anyOf:
- type: number
- type: 'null'
title: Charge
lattice:
$ref: '#/components/schemas/TypedLatticeDict'
sites:
items:
$ref: '#/components/schemas/TypedSiteDict'
type: array
title: Sites
properties:
anyOf:
- $ref: '#/components/schemas/TypedAggregateProperitesDict'
- type: 'null'
type: object
required:
- '@module'
- '@class'
- lattice
- sites
title: TypedStructureDict
TypedGrainBoundaryDict:
properties:
'@module':
type: string
title: '@Module'
'@class':
type: string
title: '@Class'
lattice:
$ref: '#/components/schemas/TypedLatticeDict'
sites:
items:
$ref: '#/components/schemas/TypedSiteDict'
type: array
title: Sites
init_cell:
$ref: '#/components/schemas/TypedStructureDict'
rotation_axis:
items:
type: integer
type: array
title: Rotation Axis
rotation_angle:
type: number
title: Rotation Angle
gb_plane:
items:
type: integer
type: array
title: Gb Plane
join_plane:
items:
type: integer
type: array
title: Join Plane
vacuum_thickness:
type: number
title: Vacuum Thickness
ab_shift:
items:
type: number
type: array
title: Ab Shift
oriented_unit_cell:
$ref: '#/components/schemas/TypedStructureDict'
type: object
required:
- '@module'
- '@class'
- lattice
- sites
- init_cell
- rotation_axis
- rotation_angle
- gb_plane
- join_plane
- vacuum_thickness
- ab_shift
- oriented_unit_cell
title: TypedGrainBoundaryDict
Meta:
properties:
api_version:
type: string
title: Api Version
description: A string containing the version of the Materials API implementation, e.g. v0.9.5
default: 0.86.4rc5.dev1+g77c2c1315
time_stamp:
type: string
format: date-time
title: Time Stamp
description: A string containing the date and time at which the query was executed
total_doc:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Total Doc
description: The total number of documents available for this query
facet:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Facet
description: A dictionary containing the facets available for this query
additionalProperties: true
type: object
title: Meta
description: Meta information for the MAPI Response.
Error:
properties:
code:
type: integer
title: Code
description: The error code
message:
type: string
title: Message
description: The description of the error
type: object
required:
- code
- message
title: Error
description: Base Error model for General API.
TypedSpeciesDict:
properties:
element:
anyOf:
- type: string
- type: 'null'
title: Element
oxidation_state:
anyOf:
- type: number
- type: 'null'
title: Oxidation State
spin:
anyOf:
- type: number
- type: 'null'
title: Spin
occu:
anyOf:
- type: number
- type: 'null'
title: Occu
type: object
title: TypedSpeciesDict
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
ApiKeyAuth:
descriptions: MP API key to authorize requests
name: X-API-KEY
in: header
type: apiKey