f-Spectra Manual

f-Spectra User Manual

(Version 3, September 2016)

Table of Contents

  • Introduction and Installation
  • Quick Start
  • Advanced Topics
  • Full Menu and Commands
    • Main window
    • Input Parameters window
    • Fitting window
    • Options for Calculation window
    • Show Statevectors and Properties window
    • Superposition Model window
    • Differential Evolution window
    • Chart window
    • Authenticity Key window
  • Frequency Asked Questions
  • Licence Agreement Form

[Previous: ]|[Table of Contents]|[Next: ]

Copyright (C) 2016. YEUNG Yau Yuen. All Rights Reserved.


f-Spectra Manual: Introducton and Installation

Introducton

This computer package (f-Spectra) is developed with a user-friendly graphical interface to do fitting and prediction of free-ion parameters, crystal field parameters, correlation crystal field parameters and superposition model parameters to the energy levels of f-shell ions as well as calculations of transition intensities, energy levels (with identification of irreducible representations) and statevectors etc. By using this software, you must have agreed with the following conditions of usage (otherwise you should not use it):

  1. Copyright for the computer program, source code and related data files rest with the author - Prof. YEUNG Yau Yuen (the software developer) and all users have nothing to do with it.
  2. As this package is provided free-of-charge, the software developer will not bear any warranty and liability on its usage.
  3. For whatever purpose, the user shall not copy or redistribute the package to other persons, nor make it available in the public domain.
  4. The user will not allow other person(s) to use this package without the software developer’s prior consent.
  5. The user will report to the software developer any errors or problems found on using this package.

This f-Spectra computer package was developed by Professor YEUNG Yau Yuen for spectroscopic analysis of f-shell ions in vapour state or doped at arbitrary symmetry sites in host crystals. It has been tested to work in the Windows XP/Vista/7/8/10 systems as well as the Linux platform via the WINE program. Please send feedback or comments to yeungy@acm.org or yeung.acm@gmail.com.

Installation

Run the installation package (f-Spectra_install.exe) and it will unzip itself for automatic installation. You should keep the system files if they are newer than the ones to be installed.

After installation, you should go to the f-Spectra folder (usually located at C:\Program Files (x86)\f-Spectra\) and unzip the files rme.zip and cfp.zip into the f-Spectra folder so that their embedded files will be inserted into the folders rme and cfp, respectively.

For the first time of running this package, the window below is displayed to ask you to provide the Auth Key:

You should copy the Machine ID and send email to yeungy@acm.org or yeung.acm@gmail.com for getting the Auth Key.

To open or save files in Excel format, your computer system need to have either MS Excel or equivalent spreadsheet programme from OpenOffice.org or Kingsoft Office. Otherwise, only plain texts files will be used to input or output data or parameters.

[Previous: Table of Contents]|[Table of Contents]|[Next: Quick Start]


f-Spectra Manual : Quick Start

Quick Start

1. Input Parameters

  1. After running the f-Spectra Package, you would see the following Input Parameters window for the input or editing of the major and minor free-ion parameters as well as the crystal field parameters. Select File->New (or Load file) from the menu to create a new set of input parameters (or open an existing parameter file *.par).

Figure 1: Window for input of free-ion and crystal field parameters

If you cannot find the above window, you may click the menu Run->Input Parameters in the main window with the caption “f-Spectra (f-shell Spectroscopic Analysis Package)”.

  2. For the first three entries, you must provide the correct chemical symbol and charge for a lanthanide (4f shell) or actinide (5f shell) ion name while the crystal, system features and reference source could be anything but there should be no quotation marks included.
  3. In the frame for the Major Free-ion Parameters, you may choose the appropriate type of the parameters (Racah or Slater) for the electron-electron repulsion while the first entry (Eav or E0) could be set to zero if you do not know. Initial or approximate values of those Racah or spin-orbit coupling parameters are widely available from the literature. The no. of f-shell electrons N should have been automatically generated after you entered the correct chemical symbol and charge (see the above Step 2.1.2) while the no. of fold of symmetry axis n could be a natural number from 1 to 6, depending on the actual site symmetry (for crystal field analysis).
  4. In the frame for Minor Free-ion Parameters, if you want to adopt the conventional practice to make Mk, Pk constrained as M0:M2:M4=1:0.56: 0.38 and P2: P4: P6 = 1: 0.75: 0.5, you just need to input the value of M0 and P2, leaving other Mk and Pk blank. Of course, you may use other ratios for them and then you need to input their actual values.
  5. In the frame for Crystal Field Parameters, you should first choose the appropriate point group for the site symmetry of the f-shell ion. For low-symmetry sites with complex crystal field, another column labelled with Im Bkq will appear for the input of the imaginary components of the Bkq parameters. You may choose other conventions (e.g. Stevens or unitary operators) for the crystal field parameters from the menu Functions->CFP conversion or rotate them in other coordinates frame by the menu Functions->Rotate CFP.
  6. Note that the bracket values are for the errors of the parameters concerned and they could be omitted (if unknown) but not be set zero.
  7. Choose FileàSave File from the menu to save your input parameters in a plain text file with the default extension of *.par. You may open it with any word processor and the parameter values (but not its data structure) and must save it as a plain text file.

2. Calculation of Crystal Field Energies

To calculate the energy levels using the given parameters, choose Run->Calculations with Options->Real/Complex Crystal Field from the menu. The following “Options for Calculations” window will be displayed.

Options for Calculations window

If the default settings are OK, you should click the Run button to start the calculation which will usually be completed within a minute for a system with less than 4 or more than 10 f-shell electrons. For those systems with 4 to 10 f-shell electrons at low-symmetry sites, it may take several minutes up to around an hour, depending on the speed of your computing machine.

Three plain texts will be generated and shown with the following file name extension (with filename taken from that of the *.par file):

  • *.eng for the label 2S+1LJ, crystal quantum number mu, irreducible representation IR, energy, Zeeman splitting and s’ (with second order correction), degeneracy and 3 largest statevector components of each crystal field level.
  • *.ev for the coefficients of every statevector (quantum numbers for each statevector component are given at the beginning of the file).
  • *.gen for general information of the fit or calculation, including input parameters, output energies and statevectors etc.

3. Fitting to Observed Crystal Field Energy Levels

  1. To start the crystal field fit, choose Run->Fit Real/Complex Crystal Field from the menu. Depending on the speed of your computer, you will get the following window “Get file of experimental data for energies” within a few minutes (for ions with 1-3 or 11-13 f-shell electrons) or up to a few hours (for ions with 6-8 f-shell electrons at low-symmetry sites). Choose an existing for the experimental energies which have been input into a specific format (see sample files like *eng.xls). You may select the example file called “default_eng.xls”.

get file of experimental data for energies
Figure 2: window “Get file of experimental data for energies”

  2. Then, the following Fitting window will be displayed to show the input parameter values and the observed energies.

Figure 3: Fit Window to control the fit processes and to show the results of fits or calculations

  3. Click the [Update Energies] or [Update SV] button to get the calculated values of the energies and related spectroscopic properties which are further displayed in the State Properties and Statevectors window. When any state or row in the above RHS table is clicked, the corresponding statevector coefficient and quantum numbers will be shown in the RHS table of the Statevector window.

Figure 4: State Properties and Statevectors window to show the energies, spectroscopic properties (like the g-factor for Zeeman splitting, mu for crystal quantum number, IR for irreducible representation, (2S+1)L label and J value) and statevector components.

  4. In the LHS table of the Fit Window, set option value in the Opt. column as follows:
  • 1 to freely fit the parameter,
  • 0 to fix its value in the “Final_fit” column and
  • -1 (for M2,4 or P4,6) to have certain fixed ratio with other parameters (either M0 or P2 for -1 or a particular parameter in the nth row for –n) as given in the Initial column. The linked parameter will be indicated with the “->” symbol.

    To carry out the fit, click the [Run] button or select Run->Free-ion and CF parameters fit. After each round of fit, you should click the [Update Energies] or [Update SV] button to update the calculated values of the energies or statevectors (including update of energies). The latter process is required before you carry out any refit.

  5. Under the Options menu, you may discard the values of the present fit as shown in the “Final_fit” column and reset them to those of the previous fit or to the initial values. You will probably need to run the fit several times until there is no significant change in the RMS Dev (root-mean-squares deviation) or to get out of any possible local minima in the fitting space. In the LHS table, note that N is the total number of observed energies selected for the fit and Np is the total number of freely-varying parameters (i.e. with value 1 in the Opt. column) involved in the fit. The S.E. (standard error), which is shown in the last row of the Error column, is defined as S.E. = SQRT(RMS dev/(N – Np)).
  6. If the results of fit are satisfactory, save the energies (RHS table) and parameters (LHS table) as two separate Excel or plain text files by choosing an appropriate command in the File menu. They could be re-used for future fits of other options or similar systems. The fitted values of parameters could be exported back to the Crystal Field Parameter window (see Figure 1) by selecting File->Export Parameters to Input window where the parameter values in the Final_fit and their errors will be updated.

[Previous: Introduction and Installation]|[Table of Contents]|[Next: Advanced Topics]


f-Spectra Manual: Introducton and Installation

Advanced Topics

How to fit or calculate free-ion energy levels

1. Input Parameters

  • Similar to the Subsection 1 of Quick Start, you should see the following Input Parameters window for the input or editing of the major and minor free-ion parameters after running the f-Spectra package. Select File->New (or Load file) from the menu to create a new set of input parameters (or open an existing parameter file *.par).
  • As shown in the Figure 5 below, you should choose Free-ion for the point group and then n will become 1. There is no crystal field parameter for input while entries for free-ion parameters will remain the same. You may refer to Steps 1-7 of Subsection 1 in the Quick Start.

Figure 5: Setting for the input of free-ion parameters.

2. Calculation of Free-ion Energies
To calculate the energy levels using the given parameters, choose Run->Calculations with Options->Free Ion Calculation from the menu. If you are fine with the default settings shown in the window, you should click the [Run] button to start the calculation which will usually be completed within a minute.

Three plain texts will be generated and shown with the following file name extension (with filename taken from that of the *.par file):

  • *.eng for the energy, J, gJ-factor and 3 largest statevector components of each state plus information for the reduced matrix elements of various operators.
  • *.ev for the coefficients of every statevector (quantum numbers for each statevector component are given at the beginning of the file).
  • *.gen for general information of the fit or calculation, including input parameters, output energies and statevectors etc.

3. Fitting to Observed Free-ion Energy Levels
To start the crystal field fit, choose Run->Fit Free Ion Hamiltonian from the menu. As shown in the Figure 6 below, the Fit window is similar to that shown in Figure 3 except the followings:

  • There is no column for the IR in the RHS panel.
  • There is no row for crystal field parameters in the LHS panel.
  • The fit should converge much faster than that for the fit of the crystal field energy levels.

The other aspects are similar to those given in Subsection 3 in Quick Start. You may click the Ultimate Fit button to get the fit done very quickly.

Figure 6: Fit Free-ion Parameters window

[Previous: Quick Start ]|[Table of Contents]|[Next: Full Menu and Commands]


f-Spectra Manual: Personal Licence and Collaboration Agreement

f-Spectra (f-shell SpectroscopicAnalysis Package)
Personal Licence and Collaboration Agreement

I clearly understand and fully agree with the following terms for using the captioned Microsoft Windows-based computer package which can do fitting and prediction of free-ion parameters, crystal field parameters, correlation crystal field parameters and superposition model parameters to the energy levels of f-shell ions as well as calculations of transition intensities, energy levels (with identification of irreducible representations) and statevectors etc:

  1. Copyright for the computer program, source code and related data files rest with the author - Prof. YEUNG Yau Yuen and I have nothing to do with it.
  2. As this package is provided free-of-charge, the author will not bear any warranty and liability on its usage.
  3. For whatever purpose, I shall not copy or redistribute the package to other persons, nor make it available in the public domain.
  4. I will not allow other person(s) to use this package without the author’s prior consent.
  5. I will report to the author any errors or problems found on using this package.
  6. I am willing to use this package to conduct collaborative research with Prof. Yeung of which the research findings will lead to joint publications with co-authorship.

User’s Full Name: _____________________________
User’s Post: __________________________________
User’s Institution (Department and university name):
______________________________________________________

Full address: ___________________________________________

______________________________________________________

Signature: ________________________Date: __________________

[Previous: Frequency Asked Questions]|[Table of Contents]


Fitting window

After selecting a kind of fit, the following Fitting window will be displayed to show the input parameter values and the observed energies.

Figure 3: Fitting Window to control the fit processes and to show the results of fits or calculations


Input Parameters

2.1. Input Parameters

2.1.1. After running the f-Spectra Package, you should see the following Input Parameters window for the input or editing of the major and minor free-ion parameters as well as the crystal field parameters. Select File àNew (or Load file) from the menu to create a new set of input parameters (or open an existing parameter file *.par).

Figure 1: Window for input of free-ion and crystal field parameters

If you cannot find the above window, you may click the menu Run àInput Parameters in the main window with the caption “f-Spectra (f-shell Spectroscopic Analysis Package)”.

2.1.2. For the first three entries, you must provide the correct chemical symbol and charge for a lanthanide (4f shell) or actinide (5f shell) ion name while the crystal, system features and reference source could be anything but there should be no quotation marks included.

2.1.3. In the frame for the Major Free-ion Parameters, you may choose the appropriate type of the parameters (Racah or Slater) for the electron-electron repulsion while the first entry (Eav or E0) could be set to zero if you do not know. Initial or approximate values of those Racah or spin-orbit coupling parameters are widely available from the literature. The no. of f-shell electrons N should have been automatically generated after you entered the correct chemical symbol and charge (see the above Step 2.1.2) while the no. of fold of symmetry axis n could be a natural number from 1 to 6, depending on the actual site symmetry (for crystal field analysis).

2.1.4. In the frame for Minor Free-ion Parameters, if you want to adopt the conventional practice to make Mk, Pk constrained as M0:M2:M4=1:0.56: 0.38 and P2: P4: P6 = 1: 0.75: 0.5, you just need to input the value of M0 and P2, leaving other Mk and Pk blank. Of course, you may use other ratios for them and then you need to input their actual values.

2.1.5. In the frame for Crystal Field Parameters, you should first choose the appropriate point group for the site symmetry of the f-shell ion. For low-symmetry sites with complex crystal field, another column labelled with Im Bkq will appear for the input of the imaginary components of the Bkq parameters. You may choose other conventions (e.g. Stevens or unitary operators) for the crystal field parameters from the menu Functions àCFP conversion or rotate them in other coordinates frame by the menu Functions àRotate CFP.

2.1.6. Note that the bracket values are for the errors of the parameters concerned and they could be omitted (if unknown) but not be set zero.

2.1.7. Choose File àSave File from the menu to save your input parameters in a plain text file with the default extension of *.par. You may open it with any word processor and the parameter values (but not its data structure) and must save it as a plain text file.