Compound¶

class curie.Compound(compound, weights=None, density=None)[source]¶

Data and properties of atomic compounds

The compound class provides the same functionality as the element class, but for compounds of atomic elements rather than the individual atomic elements. The compound is described by a set of elements, a set of weights for each element, and a density.

The weights can be either given as atom-weights, e.g. in H2O the atom weights are 0.67 for H and 0.33 for O, or as mass-weights, e.g. brass is 0.33 Zn by weight and 0.67 Cu by weight. Some preset compounds are available; their names can be found by printing ci.COMPOUND_LIST.

Parameters:

compoundstr

The name of the compound. If the compound is in ci.COMPOUND_LIST, the weights and density will take preset values, if not given. If the name of the compound is given in chemical notation, e.g. NaCl or H2O2, the atom-weights can be inferred if not given explicitly. Note that full chemical notation is not supported, so Ca3(PO4)2 must be written as Ca3P2O8. Decimal weights are supported, e.g. C0.5O is equivalent to CO2.

weightsdict, str or pd.DataFrame, optional

The weights of each element in the compound. Multiple formats are supported. If weights is a dict, it must be formatted as {‘el1’:wt1, ‘el2’:wt2}, where atom-weights are positive, and mass-weights are negative.

If weights is a pandas DataFrame, it must contain an ‘element’ column, and one of ‘weight’, ‘atom_weight’, or ‘mass_weight’. If ‘weight’ is the column given, the convention of positive atom-weights and negative mass-weights is followed.

If weights is a str, it can either be formatted as ‘el1:wt1, el2:wt2’, or it can be a path to a .csv, .json or .db file. These files must contain the same information as the DataFrame option, and can contain weights for multiple compounds, if ‘compound’ is one of the columns/keys.

If a .json file, it must follow the ‘records’ formatting convention (see pandas docs).

densityfloat, optional

Density of the compound in g/cm^3. The density is required for the cm.attenuation(), cm.S(), cm.range() and cm.plot_range() functions, but is an optional argument in each of those functions if not provided at construction. Can also be specified by using a ‘density’ column/key in the file/DataFrame for weights.

Examples

>>> print('Silicone' in ci.COMPOUND_LIST)
True
>>> cm = ci.Compound('Silicone') # preset compound
>>> print(list(map(str, cm.elements)))
['H', 'C', 'O', 'Si']
>>> cm = ci.Compound('H2O', density=1.0)
print(cm.weights)
  element  Z  atom_weight  mass_weight
0       H  1     0.666667     0.111907
1       O  8     0.333333     0.888093
>>> cm = ci.Compound('Brass', weights={'Zn':-33,'Cu':-66})
>>> print(cm.weights)
  element   Z  atom_weight  mass_weight
0      Zn  30     0.327041     0.333333
1      Cu  29     0.672959     0.666667
>>> cm.saveas('brass.csv')

Attributes:

namestr: The name of the compound.
weightspd.DataFrame: The weights for each element in the compound. DataFrame columns are ‘element’, ‘Z’, ‘mass_weight’, ‘atom_weight’.
densityfloat: Density of the compound in g/cm^3. The density is used in calculations of charged particle dEdx and photon attenuation, so if the density was not explicitly given at construction, you can assign a new density using cm.density = new_density if needed, or using the density keyword in either of those functions.
elementslist of ci.Element: Elements in the compound.
mass_coeffpd.DataFrame: Table of mass-attenuation coefficients as a function of photon energy, from the NIST XCOM database. Energies are in keV, and mass-attenuation coefficients, or mu/rho, are given in cm^2/g. DataFrame columns are ‘energy’, ‘mu’ and ‘mu_en’ for the mass-energy absorption coefficient.

Methods

`S`(energy[, particle, density])	Charged particle stopping power in matter
`attenuation`(energy, x[, density])	Photon attenuation in matter
`mu`(energy)	Mass-attenuation coefficient
`mu_en`(energy)	Mass energy-absorption coefficient
`plot_S`([particle, energy])	Plot the stopping power in the compound
`plot_mass_coeff`([energy])	Plot the mass-attenuation coefficient in the compound
`plot_mass_coeff_en`([energy])	Plot the mass energy-absorption coefficient in the compound
`plot_range`([particle, energy, density])	Plot the charged particle range in the compound
`range`(energy[, particle, density])	Charged particle range in matter
`saveas`(filename[, replace])	Save the compound definition to a file

S(energy, particle='p', density=None)[source]¶

Charged particle stopping power in matter

Calculate the stopping power, S=-dE/dx, for a given ion as a function of the ion energy in MeV. Units of S are MeV/cm. To return stopping power in units of MeV/(mg/cm^2), use option density=1E-3. The stopping power is calculated using the Element.S() methods for each element in cm.elements, added using Bragg’s rule.

Parameters:

energyarray_like: Incident ion energy in MeV.
particlestr, optional: Incident ion. For light ions, options are ‘p’ (default), ‘d’, ‘t’, ‘a’ for proton, deuteron, triton and alpha, respectively. Additionally, heavy ions can be specified either by element or isotope, e.g. ‘Fe’, ‘40CA’, ‘U’, ‘Bi-209’. For light ions, the charge state is assumed to be fully stripped. For heavy ions the charge state is handled by a Bohr/Northcliffe parameterization consistent with the Anderson-Ziegler formalism.
densityfloat, optional: Density of the compound in g/cm^3. Default behavior is to use Compound.density. To return stopping power in units of MeV/(mg/cm^2), i.e. the mass-stopping power, use density=1E-3.

Returns:

stopping_powernumpy.ndarray: Stopping power, S=-dE/dx, for a given ion as a function of the ion energy in MeV. Units of S are MeV/cm.

Examples

>>> cm = ci.Compound('SrCO3', density=3.5)
>>> print(cm.S(60.0))
27.196387031247834
>>> print(cm.S(55.0, density=1E-3)) ### S in MeV/(mg/cm^2)
0.008307827781861116

attenuation(energy, x, density=None)[source]¶

Photon attenuation in matter

Calculate the attenuation factor I(x)/I_0 = e^(-mu*x) for a given photon energy (in keV) and slab thickness (in cm).

Parameters:

energyarray_like: Incident photon energy in keV.
xfloat: Thickness of slab of given compound, in cm.
densityfloat, optional: Density of the compound in g/cm^3. Default behavior is to use Compound.density, which must be supplied at construction.

Returns:

attenuationnumpy.ndarray: The slab attenuation factor as an absolute number (i.e. from 0 to 1). E.g. if the incident intensity is I_0, the transmitted intensity I(x) is I_0 times the attenuation factor.

Examples

>>> cm = ci.Compound('SS_316') # preset compound for 316 Stainless
>>> print(cm.attenuation(511, x=0.3))
0.8199829388434694
>>> print(cm.attenuation(300, x=1.0, density=5.0))
0.5752140388004373

mu(energy)[source]¶

Mass-attenuation coefficient

Interpolates the mass-attenuation coefficient, mu/rho, for the compound along the input energy grid.

Parameters:

energyarray_like: The incident photon energy, in keV.

Returns:

munp.ndarray: Mass attenuation coefficient, mu/rho, in cm^2/g.

Examples

>>> cm = ci.Compound('H2O')
>>> print(cm.mu(200))
0.13703928393005832

mu_en(energy)[source]¶

Mass energy-absorption coefficient

Interpolates the mass-energy absorption coefficient, mu_en/rho, for the compound along the input energy grid.

Parameters:

energyarray_like: The incident photon energy, in keV.

Returns:

mu_ennp.ndarray: Mass energy absorption coefficient, mu_en/rho, in cm^2/g.

Examples

>>> cm = ci.Compound('H2O')
>>> print(cm.mu_en(200))
0.029671598667776862

plot_S(particle='p', energy=None, **kwargs)[source]¶

Plot the stopping power in the compound

Creates a plot of the charged particle stopping power (in MeV/(mg/cm^2)) in the compound as a function of the incident ion energy (in MeV).

Parameters:

particlestr: Incident ion. For light ions, options are ‘p’ (default), ‘d’, ‘t’, ‘a’ for proton, deuteron, triton and alpha, respectively. Additionally, heavy ions can be specified either by element or isotope, e.g. ‘Fe’, ‘40CA’, ‘U’, ‘Bi-209’.
energyarray_like, optional: Energy grid on which to plot, replacing the default energy grid. Units are in MeV.

Other Parameters:

**kwargs: Optional keyword arguments for plotting. See the plotting section of the curie API for a complete list of kwargs.

Examples

>>> cm = ci.Compound('He') # same as element
>>> cm.plot_S(particle='a')
>>> cm = ci.Compound('Kapton')
>>> cm.plot_S(particle='d')

plot_mass_coeff(energy=None, **kwargs)[source]¶

Plot the mass-attenuation coefficient in the compound

Creates a plot of the mass-attenuation coefficient (in cm^2/g) as a function of photon energy in keV.

Parameters:

energyarray_like, optional: Energy grid on which to plot, replacing the default energy grid. Units are in keV.

Other Parameters:

**kwargs: Optional keyword arguments for plotting. See the plotting section of the curie API for a complete list of kwargs.

Examples

>>> cm = ci.Compound('Fe')
>>> cm.plot_mass_coeff()
>>> cm = ci.Compound('H2O')
>>> cm.plot_mass_coeff(style='poster')

plot_mass_coeff_en(energy=None, **kwargs)[source]¶

Plot the mass energy-absorption coefficient in the compound

Creates a plot of the mass energy-absorption coefficient (in cm^2/g) as a function of photon energy in keV.

Parameters:

energyarray_like, optional: Energy grid on which to plot, replacing the default energy grid. Units are in keV.

Other Parameters:

**kwargs: Optional keyword arguments for plotting. See the plotting section of the curie API for a complete list of kwargs.

Examples

>>> cm = ci.Compound('Silicone') # preset compound

Example plotting the mass-attenuation coefficient together with the mass energy-absorption coefficient, on the same axes.

>>> f,ax = cm.plot_mass_coeff(return_plot=True)
>>> cm.plot_mass_coeff_en(f=f, ax=ax)

plot_range(particle='p', energy=None, density=None, **kwargs)[source]¶

Plot the charged particle range in the compound

Creates a plot of the charged particle range (in cm) in the compound as a function of the incident ion energy (in MeV).

Parameters:

particlestr: Incident ion. For light ions, options are ‘p’ (default), ‘d’, ‘t’, ‘a’ for proton, deuteron, triton and alpha, respectively. Additionally, heavy ions can be specified either by element or isotope, e.g. ‘Fe’, ‘40CA’, ‘U’, ‘Bi-209’.
energyarray_like, optional: Energy grid on which to plot, replacing the default energy grid. Units are in MeV.
densityfloat, optional: Density of the compound in g/cm^3. Default behavior is to use Compound.density.

Other Parameters:

**kwargs: Optional keyword arguments for plotting. See the plotting section of the curie API for a complete list of kwargs.

Examples

>>> cm = ci.Compound('Bronze', weights={'Cu':-80, 'Sn':-20}, density=8.9)
>>> f,ax = cm.plot_range(return_plot=True)
>>> cm.plot_range(particle='d', f=f, ax=ax)

range(energy, particle='p', density=None)[source]¶

Charged particle range in matter

Calculates the charged particle range in the compound, in cm. Incident energy should be in MeV, and the particle type definition is identical to Compound.S().

Parameters:

energyarray_like: Incident ion energy in MeV.
particlestr, optional: Incident ion. For light ions, options are ‘p’ (default), ‘d’, ‘t’, ‘a’ for proton, deuteron, triton and alpha, respectively. Additionally, heavy ions can be specified either by element or isotope, e.g. ‘Fe’, ‘40CA’, ‘U’, ‘Bi-209’. For light ions, the charge state is assumed to be fully stripped. For heavy ions the charge state is handled by a Bohr/Northcliffe parameterization consistent with the Anderson-Ziegler formalism.
densityfloat, optional: Density of the compound in g/cm^3. Default behavior is to use Compound.density, which must be supplied at construction.

Returns:

rangenp.ndarray: Charged particle range in the compound, in cm.

Examples

>>> cm = ci.Compound('Fe') # same behavior as element
>>> print(cm.range(60.0))
0.5858151125192633
>>> cm = ci.Compound('SS_316') # preset compound
>>> print(cm.range(60.0))
0.5799450918147814

saveas(filename, replace=False)[source]¶

Save the compound definition to a file

The weights and density of the compound can be saved to one of the following file formats: .csv, .json, .db. If the file exists, the data will be appended, unless replace=True, in which case the file will be replaced. If a definition for the compound exists in the file already, it will be replaced.

Parameters:

filenamestr: Filename where the compound will be saved. Available formats are .csv, .json and .db.
replacebool, optional: If True, replace the file if it exists. Default False, which appends the data to the file.

Examples

>>> cm = ci.Compound('Brass', weights={'Zn':-33,'Cu':-66})
>>> cm.saveas('brass.csv')
>>> cm = ci.Compound('Water', weights={'H':2, 'O':1}, density=1.0)
>>> cm.saveas('water.json')

Compound¶

Table of Contents

Previous topic

Next topic

This Page