Getting started¶
The same calls in TypeScript and in Python. Every example on this page is run when the site is built, and the output shown is what it printed.
TypeScript¶
npm install symcrys
symcrys is the crystallographic API: the 32 crystal classes, without time reversal. A crystal
class is named by its key, the ITC short symbol of the class ('32', 'm-3m'; - stands for
the overbar).
// Getting started with symcrys in TypeScript: the crystallographic API, `symcrys`.
import { allowedProperties, operations, pointGroup, settings, symbol, tensorForm } from 'symcrys';
// A crystal class by its key: the ITC short symbol of the class.
console.log(pointGroup('32'));
// Symbols and settings: ITC is the default convention, Birss an option.
console.log(symbol('32'), symbol('32', { convention: 'birss' }), symbol('32', { form: 'schoenflies' }));
console.log(settings('32').map((s) => `${s.index}: ${s.symbol}${s.isDefault ? ' (default)' : ''}`));
// The operations: Cartesian matrices, x ∥ a and z ∥ c for hexagonal axes.
console.log(operations('32').length, operations('32')[1].matrix);
// The form of a tensor: by its specification, or by the name of a property.
const SHG = { rank: 3, parity: 'polar', intrinsic: 'jk' } as const;
console.log(tensorForm('mm2', SHG).parameters); // the free components as index lists: xxz, yyz, zxx, zyy, zzz
console.log(allowedProperties('32'));
Output:
{
key: '32',
crystalSystem: 'trigonal',
order: 6,
centrosymmetric: false,
polar: false,
chiral: true,
laueClass: '-3m'
}
321 32 D3
[ '1: 312', '2: 321 (default)' ]
6 [
[ -0.5, -0.8660254037844386, 0 ],
[ 0.8660254037844386, -0.5, 0 ],
[ 0, 0, 1 ]
]
[ [ 0, 0, 2 ], [ 1, 1, 2 ], [ 2, 0, 0 ], [ 2, 1, 1 ], [ 2, 2, 2 ] ]
[ 'piezoelectric', 'gyrotropic' ]
The magnetic point groups are in symcrys/magnetic, under the same names. There an operation
carries timeReversal, and a tensor specification timeParity:
// The magnetic API, `symcrys/magnetic`: the same function names for the 122 magnetic point groups.
import { allowedProperties, operations, pointGroup, tensorForm } from 'symcrys/magnetic';
console.log(pointGroup("4'/mmm'"));
console.log(operations("4'/mmm'")[2].timeReversal);
console.log(allowedProperties("m'm'2"));
console.log(tensorForm("m'm'2", 'ferromagnetic').parameters); // M_s along z
Output:
{
key: "4'/mmm'",
type: 'III',
crystalClass: '4/mmm',
crystalSystem: 'tetragonal',
order: 16,
centrosymmetric: true,
polar: false,
chiral: false,
laueClass: '4/mmm'
}
true
[
'pyroelectric',
'piezoelectric',
'gyrotropic',
'ferromagnetic',
'magnetoelectric',
'piezomagnetic'
]
[ [ 2 ] ]
The plane groups and the plane point groups are in symcrys/plane, in the lattice basis
(Conventions, “Plane groups”):
// The plane API, `symcrys/plane`: the 17 plane groups and the 10 plane point groups, in the lattice basis.
import { asymmetricUnit, operations, planeGroup, symmetryElements, wyckoffPositionOf } from 'symcrys/plane';
console.log(planeGroup('p4gm'));
console.log(operations('p4gm')[4]); // b 1/4,y: -x+1/2,y+1/2
console.log(wyckoffPositionOf('p4gm', [0.5, 0])); // a point on the 2-fold centre at 1/2,0
console.log(asymmetricUnit('p4gm').vertices);
console.log(symmetryElements('p4gm').rotations.map((r) => `${r.order} at ${r.point.join(',')}`));
Output:
{
key: 'p4gm',
number: 12,
fullSymbol: 'p4gm',
pointGroup: '4mm',
pointGroupSetting: 1,
crystalSystem: 'square',
centring: [],
origin: 'at 41g',
order: 8
}
{ matrix: [ [ -1, 0 ], [ 0, 1 ] ], translation: [ 0.5, 0.5 ] }
{
letter: 'b',
multiplicity: 2,
siteSymmetry: '2.mm',
coordinates: [ '1/2,0', '0,1/2' ]
}
[ [ 0, 0 ], [ 0.5, 0 ], [ 0, 0.5 ] ]
[
'4 at 0,0',
'4 at 1,0',
'4 at 0.5,0.5',
'4 at 0,1',
'4 at 1,1',
'2 at 0.5,0',
'2 at 0,0.5',
'2 at 1,0.5',
'2 at 0.5,1'
]
Without a build step, copy dist/ of the package (from the npm tarball, or from the release on
GitHub) next to your code and import dist/index.js, dist/magnetic.js or dist/plane.js: every module imports
only relative .js paths.
Python¶
pip install symcrys
The names are those of TypeScript in snake_case, an options object becomes keyword arguments, and arrays of numbers become NumPy arrays.
import symcrys
symcrys.point_group("32")
{'key': '32',
'crystal_system': 'trigonal',
'order': 6,
'centrosymmetric': False,
'polar': False,
'chiral': True,
'laue_class': '-3m'}
symcrys.symbol("32"), symcrys.symbol("32", convention="birss"), symcrys.symbol("32", form="schoenflies")
('321', '32', 'D3')
symcrys.operations("32")[1]["matrix"]
array([[-0.5 , -0.8660254, 0. ],
[ 0.8660254, -0.5 , 0. ],
[ 0. , 0. , 1. ]])
SHG = {"rank": 3, "parity": "polar", "intrinsic": "jk"}
form = symcrys.tensor_form("mm2", SHG)
form["parameters"] # the free components as index lists: xxz, yyz, zxx, zyy, zzz
array([[0, 0, 2],
[1, 1, 2],
[2, 0, 0],
[2, 1, 1],
[2, 2, 2]])
symcrys.allowed_properties("32")
['piezoelectric', 'gyrotropic']
The magnetic API is the module symcrys.magnetic:
from symcrys import magnetic
magnetic.allowed_properties("m'm'2"), magnetic.tensor_form("m'm'2", "ferromagnetic")["parameters"]
(['pyroelectric',
'piezoelectric',
'gyrotropic',
'ferromagnetic',
'magnetoelectric',
'piezomagnetic'],
array([[2]]))
The plane API is the module symcrys.plane:
from symcrys import plane
plane.wyckoff_position_of("p6mm", [1 / 3, 2 / 3]), plane.asymmetric_unit("p6mm")["vertices"]
({'letter': 'b',
'multiplicity': 2,
'site_symmetry': '3m.',
'coordinates': ['1/3,2/3', '2/3,1/3']},
array([[0. , 0. ],
[0.5 , 0. ],
[0.66666667, 0.33333333]]))
An error of the library raises symcrys.SymcrysError, a subclass of ValueError:
try:
symcrys.point_group("7")
except symcrys.SymcrysError as e:
print(e)
Unknown point group key: "7"
A call costs about a millisecond once its result is cached; the first call for a group takes up to about 0.1 s, the form of a rank-4 tensor up to a few tenths of a second. Fetch operations and forms once, then compute with NumPy.
What to read next¶
Which key to use for a material, crystal class or magnetic group: Two readings of a key.
Which setting and which convention, and why the components of a tensor depend on them: Conventions, in particular “Settings” and “Cartesian frame”.
How a tensor form is given (basis, parameters, relations): Tensors.
The crystal forms of a class, basic and limiting, and orbits of faces: Crystal forms, orbits and distorted crystals.