#########################################################################
# #
# Copyright (C) 2016-2018 Jan Jaeken <jan.jaeken@gmail.com> #
# #
# This file is part of Christoffel. #
# "Solving the Christoffel equation: Phase and group velocities" #
# Computer Physics Communications, 10.1016/j.cpc.2016.06.014 #
# #
# Christoffel is free software: you can redistribute it and/or modify #
# it under the terms of the GNU General Public License as published by #
# the Free Software Foundation, either version 3 of the License, or #
# (at your option) any later version. #
# #
# Christoffel is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #
# GNU General Public License for more details. #
# #
# You should have received a copy of the GNU General Public License #
# along with Christoffel. If not, see <http://www.gnu.org/licenses/>. #
# #
#########################################################################
This package contains Christoffel, a Python module for calculating wave
velocities from elastic properties. This README is structured as follows:
1) General description
2) Package content
3) How to use Christoffel
3.1) Input
3.2) Execution
3.3) Output
3.4) Visualization
4) Example
1) General description
This software is designed to determine direction-dependent acoustic phase and
group velocities by solving the Christoffel equation. For detailed information
on the inner workings of the software, we refer to the accompanying paper in
Computer Physics Communications.
2) Package content
README -- This file. You are reading it right now.
christoffel.py -- Python module containing all the objects, functions and
mathematical machinery required. Toolbox.
__init__.py -- Empty file, makes the christoffel module importable.
scansurface.py -- Script for sampling wave directions in a material, it outputs
phase velocities, group velocities and enhancement factors.
sound.in -- Example input file for the scansurface script.
*.gnu files -- Gnuplot scripts to automatically plot the output of the
scansurface script.
3) How to use Christoffel
Users are highly encouraged to take a peek into the christoffel.py module and
write their own implementations by using the module as a toolbox.
For those who do not wish to tinker much, the scansurface script and sound.in
should provide adequate functionality at the press of a button.
3.1) Input
All that is required to determine the elastic wave velocities is a material's
stiffness tensor and density. These can be entered in the sound.in file.
The sound.in file should minimally contain three things:
a) A '[SCAN]' tag in the first non-commented line to identify the file.
[SCAN]
b) The density of the material in kg/m^3.
Density = xxxx.x
c) The stiffness tensor of the material in GPa, don't forget the indentation.
Stiffness =
C11 C12 C13 C14 C15 C16
C12 C22 C23 C24 C25 C26
C13 C23 C33 C34 C35 C36
C14 C24 C34 C44 C45 C46
C15 C25 C35 C45 C55 C56
C16 C26 C36 C46 C56 C66
It can further contain these optional tags:
d) Definition of the grid to loop over.
Numtheta = int
Numphi = int -- These define a rectangular grid in spherical coordinates on
the z>0 hemisphere of all possible wave directions. Numtheta
is the number of different values taken for the polar angle
(0<=theta<pi/2) while Numphi is the number of different
values for the azimutal angle (0<=phi<2pi). We suggest setting
Numphi equal to 4*Numtheta, though you are of course free to
choose these values as you please.
e) Definition of a new z-direction.
zdir = x y z -- This will rotate the stiffness tensor so the new z-direction
will be the one specified. This does not need to be explicitly
normalized.
f) Definition of a new x-direction.
xdir = x y z -- This will rotate the stiffness tensor so the new x-direction
will be the one specified. This does not need to be explicity
normalized, nor be orthogonal to the defined zdir. However,
the zdir tag takes precedence over xdir if it is specified,
and the resulting basis will be orthonormalized accordingly.
g) Directions to output data on. Don't forget the indentation.
Directions =
x1 y1 z1
x2 y2 z2
x3 y3 z3
... -- These directions will be looped over and data will be written
to directions.dat. Useful for studying only specific special
directions, or to manually define a sampling mesh.
3.2) Execution
If the sound.in file is prepared appropriately, all that is necessary is to run
> python scansurface.py
in the appropriate directory. The directory should contain the sound.in file
and the three .py files contained within this package.
3.3) Output
The scansurface script produces 6 output files.
a) slow_secondary.dat, fast_secondary.dat, primary.dat
Acoustic information on the directions that have been looped over according
to the grid defined by the 'Numtheta' and 'Numphi' tags. Contains the data
on the slowest, intermediate and fastest acoustic mode respectively. All
three files have the same structure of 17 columns:
1 -------- Theta (rad)
2 -------- Phi (rad)
3,4,5 ---- Projection on the unit cube (cartesian)
6 -------- Phase velocity (km/s)
7 -------- Phase velocity relative to isotropic velocity (%)
8,9,10 --- Phase polarization (unit vector, dimensionless)
11 ------- Group velocity (km/s)
12 ------- Group velocity relative to isotropic velocity (%)
13,14,15 - Ray surface in cartesian coordinates (km/s)
16 ------- Power flow angle (angle between phase and group direction) (deg)
17 ------- Enhancement factor (dimensionless)
b) anisotropy.dat
If a grid was defined, this file contains information about the maximal and
minimal velocities of the three acoustic modes, and in what directions they
occur. It also provides a measure of the total anisotropy of the material.
c) directions.dat
This file contains sound velocity information about the directions
defined under the 'Directions' tag in the sound.in file. Can be empty.
d) sound.out
This file contains general information about the material of the last run,
including density, rotated and non-rotated stiffness tensor, bulk and shear
modulus and isotropic sound velocities.
3.4) Visualization
Gnuplot scripts are provided in the gnuplot subfolder to automatically plot
the data in the slow_secondary.dat, fast_secondary.dat and primary.dat files
generated by the scansurface script. A description of the naming scheme
follows, though if you are impatient you can simply run them all with:
> gnuplot ./gnuplot/*.gnu
Be advised that this may take a few minutes to complete.
The naming scheme of the scripts is as follows:
phase ----- Phase velocity
group ----- Group velocity (only absolute value)
ray ------- Ray surface (group velocity with direction)
pfangle --- Power flow angle
enh ------- Enhancement factor
pol ------- Polarization of phase velocities
relative -- For phase and group: relative to the isotropic sound velocities
sphere ---- Projection onto the unit sphere
cube ------ Projection onto the unit cube
eqar ------ Equal area projection onto the plane
stereo ---- Stereographic projection onto the plane, locally preserves shape
radius ---- Only for phase velocity, plots the data on a sphere with radius
scaled according to the absolute velocity
4) Example
The sound.in file included in this package contains the density and stiffness
tensor of GaAs and can be used for a testrun.
Raw data
{
"_id": null,
"home_page": "https://github.com/Luka140/christoffel/tree/release",
"name": "christoffel",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": "luka-groot@hotmail.nl",
"keywords": null,
"author": "Jan Jaeken",
"author_email": "jan.jaeken@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b1/ed/2aee26af98e16e17376d01ea0478a55da0a59f64b081bc0012a44d53ab20/christoffel-0.0.1.tar.gz",
"platform": null,
"description": "#########################################################################\r\n# #\r\n# Copyright (C) 2016-2018 Jan Jaeken <jan.jaeken@gmail.com> #\r\n# #\r\n# This file is part of Christoffel. #\r\n# \"Solving the Christoffel equation: Phase and group velocities\" #\r\n# Computer Physics Communications, 10.1016/j.cpc.2016.06.014 #\r\n# #\r\n# Christoffel is free software: you can redistribute it and/or modify #\r\n# it under the terms of the GNU General Public License as published by #\r\n# the Free Software Foundation, either version 3 of the License, or #\r\n# (at your option) any later version. #\r\n# #\r\n# Christoffel is distributed in the hope that it will be useful, #\r\n# but WITHOUT ANY WARRANTY; without even the implied warranty of #\r\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #\r\n# GNU General Public License for more details. #\r\n# #\r\n# You should have received a copy of the GNU General Public License #\r\n# along with Christoffel. If not, see <http://www.gnu.org/licenses/>. #\r\n# #\r\n#########################################################################\r\n\r\n\r\nThis package contains Christoffel, a Python module for calculating wave\r\nvelocities from elastic properties. This README is structured as follows:\r\n\r\n1) General description\r\n2) Package content\r\n3) How to use Christoffel\r\n 3.1) Input\r\n 3.2) Execution\r\n 3.3) Output\r\n 3.4) Visualization\r\n4) Example\r\n\r\n\r\n1) General description\r\n\r\nThis software is designed to determine direction-dependent acoustic phase and\r\ngroup velocities by solving the Christoffel equation. For detailed information\r\non the inner workings of the software, we refer to the accompanying paper in \r\nComputer Physics Communications.\r\n\r\n\r\n2) Package content\r\n\r\nREADME -- This file. You are reading it right now.\r\nchristoffel.py -- Python module containing all the objects, functions and\r\n mathematical machinery required. Toolbox.\r\n__init__.py -- Empty file, makes the christoffel module importable.\r\nscansurface.py -- Script for sampling wave directions in a material, it outputs\r\n phase velocities, group velocities and enhancement factors.\r\nsound.in -- Example input file for the scansurface script.\r\n*.gnu files -- Gnuplot scripts to automatically plot the output of the\r\n scansurface script.\r\n\r\n\r\n3) How to use Christoffel\r\n\r\nUsers are highly encouraged to take a peek into the christoffel.py module and\r\nwrite their own implementations by using the module as a toolbox.\r\n\r\nFor those who do not wish to tinker much, the scansurface script and sound.in\r\nshould provide adequate functionality at the press of a button.\r\n\r\n3.1) Input\r\n\r\nAll that is required to determine the elastic wave velocities is a material's\r\nstiffness tensor and density. These can be entered in the sound.in file.\r\n\r\nThe sound.in file should minimally contain three things:\r\n\r\na) A '[SCAN]' tag in the first non-commented line to identify the file.\r\n[SCAN]\r\n\r\nb) The density of the material in kg/m^3.\r\nDensity = xxxx.x\r\n\r\nc) The stiffness tensor of the material in GPa, don't forget the indentation.\r\nStiffness =\r\n C11 C12 C13 C14 C15 C16\r\n C12 C22 C23 C24 C25 C26\r\n C13 C23 C33 C34 C35 C36\r\n C14 C24 C34 C44 C45 C46\r\n C15 C25 C35 C45 C55 C56\r\n C16 C26 C36 C46 C56 C66\r\n\r\nIt can further contain these optional tags:\r\n\r\nd) Definition of the grid to loop over.\r\nNumtheta = int\r\nNumphi = int -- These define a rectangular grid in spherical coordinates on\r\n the z>0 hemisphere of all possible wave directions. Numtheta\r\n is the number of different values taken for the polar angle\r\n (0<=theta<pi/2) while Numphi is the number of different\r\n values for the azimutal angle (0<=phi<2pi). We suggest setting\r\n Numphi equal to 4*Numtheta, though you are of course free to\r\n choose these values as you please.\r\n\r\ne) Definition of a new z-direction.\r\nzdir = x y z -- This will rotate the stiffness tensor so the new z-direction\r\n will be the one specified. This does not need to be explicitly\r\n normalized.\r\n\r\nf) Definition of a new x-direction.\r\nxdir = x y z -- This will rotate the stiffness tensor so the new x-direction\r\n will be the one specified. This does not need to be explicity\r\n normalized, nor be orthogonal to the defined zdir. However,\r\n the zdir tag takes precedence over xdir if it is specified,\r\n and the resulting basis will be orthonormalized accordingly.\r\n\r\ng) Directions to output data on. Don't forget the indentation.\r\nDirections =\r\n x1 y1 z1\r\n x2 y2 z2\r\n x3 y3 z3\r\n ... -- These directions will be looped over and data will be written\r\n to directions.dat. Useful for studying only specific special\r\n directions, or to manually define a sampling mesh.\r\n\r\n\r\n3.2) Execution\r\n\r\nIf the sound.in file is prepared appropriately, all that is necessary is to run\r\n\r\n> python scansurface.py\r\n\r\nin the appropriate directory. The directory should contain the sound.in file\r\nand the three .py files contained within this package.\r\n\r\n\r\n3.3) Output\r\n\r\nThe scansurface script produces 6 output files.\r\n\r\na) slow_secondary.dat, fast_secondary.dat, primary.dat\r\n Acoustic information on the directions that have been looped over according\r\n to the grid defined by the 'Numtheta' and 'Numphi' tags. Contains the data\r\n on the slowest, intermediate and fastest acoustic mode respectively. All\r\n three files have the same structure of 17 columns:\r\n\r\n 1 -------- Theta (rad)\r\n 2 -------- Phi (rad)\r\n 3,4,5 ---- Projection on the unit cube (cartesian)\r\n 6 -------- Phase velocity (km/s)\r\n 7 -------- Phase velocity relative to isotropic velocity (%)\r\n 8,9,10 --- Phase polarization (unit vector, dimensionless)\r\n 11 ------- Group velocity (km/s)\r\n 12 ------- Group velocity relative to isotropic velocity (%)\r\n 13,14,15 - Ray surface in cartesian coordinates (km/s)\r\n 16 ------- Power flow angle (angle between phase and group direction) (deg)\r\n 17 ------- Enhancement factor (dimensionless)\r\n\r\nb) anisotropy.dat\r\n If a grid was defined, this file contains information about the maximal and\r\n minimal velocities of the three acoustic modes, and in what directions they\r\n occur. It also provides a measure of the total anisotropy of the material.\r\n\r\nc) directions.dat\r\n This file contains sound velocity information about the directions\r\n defined under the 'Directions' tag in the sound.in file. Can be empty.\r\n\r\nd) sound.out\r\n This file contains general information about the material of the last run,\r\n including density, rotated and non-rotated stiffness tensor, bulk and shear\r\n modulus and isotropic sound velocities.\r\n\r\n3.4) Visualization\r\n\r\nGnuplot scripts are provided in the gnuplot subfolder to automatically plot\r\nthe data in the slow_secondary.dat, fast_secondary.dat and primary.dat files\r\ngenerated by the scansurface script. A description of the naming scheme\r\nfollows, though if you are impatient you can simply run them all with:\r\n\r\n> gnuplot ./gnuplot/*.gnu\r\n\r\nBe advised that this may take a few minutes to complete.\r\n\r\nThe naming scheme of the scripts is as follows:\r\n\r\nphase ----- Phase velocity\r\ngroup ----- Group velocity (only absolute value)\r\nray ------- Ray surface (group velocity with direction)\r\npfangle --- Power flow angle\r\nenh ------- Enhancement factor\r\npol ------- Polarization of phase velocities\r\n\r\nrelative -- For phase and group: relative to the isotropic sound velocities\r\n\r\nsphere ---- Projection onto the unit sphere\r\ncube ------ Projection onto the unit cube\r\neqar ------ Equal area projection onto the plane\r\nstereo ---- Stereographic projection onto the plane, locally preserves shape\r\nradius ---- Only for phase velocity, plots the data on a sphere with radius\r\n scaled according to the absolute velocity\r\n\r\n\r\n4) Example\r\n\r\nThe sound.in file included in this package contains the density and stiffness\r\ntensor of GaAs and can be used for a testrun.\r\n\r\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0",
"summary": "Solving the Christoffel equation to calculate wave velocities from elastic properties",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/Luka140/christoffel/tree/release"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b08b0f8f94d53401f5d2a3dbe07b64aa44c0348a2cc94972975e0a4c9786f55b",
"md5": "1942d035ab25381b48ee31dc66720808",
"sha256": "7a9b107d369793813de59c71d73019954135ac6021078e92774151021fea03fb"
},
"downloads": -1,
"filename": "christoffel-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1942d035ab25381b48ee31dc66720808",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28554,
"upload_time": "2025-07-12T09:47:17",
"upload_time_iso_8601": "2025-07-12T09:47:17.754321Z",
"url": "https://files.pythonhosted.org/packages/b0/8b/0f8f94d53401f5d2a3dbe07b64aa44c0348a2cc94972975e0a4c9786f55b/christoffel-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1ed2aee26af98e16e17376d01ea0478a55da0a59f64b081bc0012a44d53ab20",
"md5": "77b5fe7fedaa93952912be1cc2c82576",
"sha256": "ca56e01637c7f2101e1fd6339bff2442df18ed345e9d61f1b83fb40aef682992"
},
"downloads": -1,
"filename": "christoffel-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "77b5fe7fedaa93952912be1cc2c82576",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30925,
"upload_time": "2025-07-12T09:47:18",
"upload_time_iso_8601": "2025-07-12T09:47:18.740276Z",
"url": "https://files.pythonhosted.org/packages/b1/ed/2aee26af98e16e17376d01ea0478a55da0a59f64b081bc0012a44d53ab20/christoffel-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 09:47:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Luka140",
"github_project": "christoffel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "christoffel"
}
JSON
