for lithium version of Exciting

Purpose: setup and explore the exciting@web. Get oriented in the exciting input file with the help of the interactive editor.

1. Overview


The exciting@web application consists of a GUI editor to edit and create exciting input files, an interface to submit and monitor exciting calculations, as well as a database to store, query, and visualize data. The structures are visualized and plots are directly displayed in the browser.

2. Installation

exciting@web is an application that runs on the eXistdb version 1.4.2. eXistdb is open source database management system built using XML technology, and can be downloaded on the eXistdb web site.

2.1 Install and configure eXist

Once the download has completed, launch the eXist installer by doing this:

java -jar eXist-setup-1.4.2-rev16251.jar

After the installer is launched, follow the prompts to complete the installation. Change the directory where you want to install eXist. During installation, you are asked to supply a password for the eXist administrator account (the "admin" password).

You should now be ready to launch eXist. Go to the directory where you installed eXist (e.g. "/users/sol/chm/eXist/"), enter the following in a console:


While eXist starts up, log output appears in the console. If eXist launched properly, you will find output similar to the following:

28 Aug 2012 17:30:47,799 [main] INFO  (Container.java [start]:74) - Started WebApplicationContext[/,eXist XML Database] 
28 Aug 2012 17:30:47,802 [main] INFO  (SocketListener.java [start]:205) - Started SocketListener on 
28 Aug 2012 17:30:47,802 [main] INFO  (Container.java [start]:74) - Started org.mortbay.jetty.Server@40e99ce5 
28 Aug 2012 17:30:47,803 [main] INFO  (JettyStart.java [run]:174) - ---------------------------------------------------------------- 
28 Aug 2012 17:30:47,803 [main] INFO  (JettyStart.java [run]:175) - eXist-db has started on port 8080. Configured contexts: 
28 Aug 2012 17:30:47,803 [main] INFO  (JettyStart.java [run]:177) - http://localhost:8080/exist
28 Aug 2012 17:30:47,803 [main] INFO  (JettyStart.java [run]:179) - ----------------------------------------------------------------

You can check status of eXist from the url http://localhost:8080/exist with a browser, but don't consider anything serious because it is not ready yet. So stop the service by pressing Ctr+C, and continue to configure the eXist-db.

Change port number and url prefix

By default the exist db starts on port 8080 and uses the prefix directory /exist/ for all access. In order to have the service running on other port without the exist prefix, open /tools/jetty/etc/jetty.xml in your eXist installation directory. Go to line 51 (line number might differ from eXist version) and change the default port number “8080” there if you want. To use a specific port number please consult your network administrator.

    <SystemProperty name="jetty.port" default="8080"/>

Go to line 134 (line number might differ from eXist version) and remove the prefix “exist”, the corresponding section looks like this:

    <Call name="addWebApplication">

Customize the url

Next is to define the url of the eXist-db to use the path where exciting interface/script is deployed. So open eXist directory /webapp/WEB-INF/controller-config.xml and make it contain only these two “root” patterns like this (line 57-58, remove or comment out line 34, 41. Note line number might differ from eXist version):

        <root pattern="/fs" path="/"/>
        <root pattern="/*" path="xmldb:exist:///db/xresult"/>

Increase the limits

The default values for connection timeout and java heap size (limits the file size that you want to import to the database) of eXist are too small, we need to use more reasonable values. Open eXist directory /tools/jetty/etc/webdefault.xml and change in line 285 (line number might differ from eXist version) .


Open eXist directory /tools/wrapper/conf/wrapper.conf and change in line 39 (line number might differ from eXist version)

# Maximum Java Heap Size (in MB)

Start the service

Before the next step, you have to start the “eXist Database Startup” from system applications, or run startup.sh from eXist/bin directory.

2.2 Import exciting@web scripts

The exciting@web application consists of a number of XQuery scripts that are stored in the database along with the data. The scripts can be download from here. To import the downloaded scripts into the eXist database there is an ant file named build.xml to automize this job. Ant is a built tool similar to make but for java applications. Ant can use the eXist db APIs to store or retrieve files from the database. For this to work the eXist path must be set to the location where the exist libraries can be found. For example /users/sol/chm/eXist/. The admin password which you entered while installing eXist must be provided here in the build.xml indicated by “*”.

    <property name="xmldb.host" value="localhost"/>
    <property name="xmldb.port" value="8080"/>
    <property name="xmldb.user" value="admin"/>
    <property name="xmldb.passwd" value="******"/>
    <property name="xmldb.url" value="xmldb:exist://${xmldb.host}:${xmldb.port}/xmlrpc/db"/>
    <property name="eXistpath" value="/users/sol/chm/eXist/"/>
    <path id="classpath.core">

Next is to copy or deploy the files into the database. Use this command

ant install

When the installation is finished, you can open a browser and go to url localhost:8080. The page should look like this.


3. Quick start

3.1 Create production account

First login as admin, and find the preferences menu on the right top of the page.


Click on the Users tab, add new user information and create user accounts for production. Make sure that the user belongs to the “contrib” group.


3.2 Login

Use the just created username and password to login again.


After the login there appears a couple of extra menu items:

public data sets
private data sets
prepare and submit input files
survey running jobs
upload data from your local computer to the database


3.3 Browse exciting database

The start page is the browse page which allows the user to find and visualize the stored calculations (new database has 0 record apparently). In order to navigate through the database one is provided with a keyword cloud. Selecting keywords allows for successively narrowing down the data set. In addition data set can be further filtered by user. The remaining entries that match all selected keywords and user are displayed in a list. Below there are examples of an existing database on the solsrv:8080 for demonstration only, no public access.


Beside the Keywords tab, one can also navigate the results in tab of Table of Elements or choose used Functionals.



A click on the title of a listed item brings up the input page of the selected calculation. The info tab gives a view on the results from the ground state calculation. Eventual properties have their own page, including visualizations and downloads in a collection of formats.




3.4 Edit exciting inputs

To start an exciting calculation, the input file must be provided. In the left main panel Inputs, you can find all your exciting input files. New input files can be created by copying (Fork bottom) one of the stored inputs or by uploading from your local machine. Below is an example input for calculation of the density of states and band structures for diamond sillicon. You can copy and save into a file and try to upload it into your Inputs collection.

  <title>Si diamond</title>
  <structure speciespath="http://xml.exciting-code.org/species/" autormt="false">
      <basevect>0.00000000000000 5.15800700290739 5.15800700290739</basevect>
      <basevect>5.15800700290739 0.00000000000000 5.15800700290739</basevect>
      <basevect>5.15800700290739 5.15800700290739 0.00000000000000</basevect>
    <species chemicalSymbol="Si" speciesfile="Si.xml">
      <atom coord="0.00000000000000 0.00000000000000 -0.00000000000000"/>
      <atom coord="0.25000000000000 0.25000000000000 0.25000000000000"/>
  <groundstate tforce="true" ngridk="4 4 4"/>
        <path steps="100">
          <point coord="0.75000   0.50000   0.25000" label="W"/>
          <point coord="0.50000   0.50000   0.50000" label="L"/>
          <point coord="0.00000   0.00000   0.00000" label="G"/>
          <point coord="0.50000   0.50000   0.00000" label="X"/>
          <point coord="0.75000   0.50000   0.25000" label="W"/>
          <point coord="0.75000   0.37500   0.37500" label="K"/>

After a click on the Fork input or upload link, the next screen will ask you to choose a file name. Then you are able to open and edit the input file. Note that saving will also validate the input against the exciting input schema.


From the text view one can toggle to the GUI mode via the Use GUI link. The GUI is an interactive editor for the exciting input file. Every section has, where applicable, an Add element and Add attribute button, signified by the blue and green plus signs. The plus sign expands a list of elements or attributes that may be added to the configuration. This way one can add atoms of a certain species, or add new attribute to the groundstate.



3.5 Add calculation service

In order to execute exciting calculations from exciting@web one has to provide a calculation service, on which machine your exciting runs. The service is configured in the preferences on the top right part of the page. Then click add service and provide an url including a port number of the calculation service.


It is possible to create calculation services yourself, which in turn allows to use different services for different versions of the exciting code or different execution modes. Instructions can be found on this [page]. Actually, the downloaded package contains a hpcservice directory, which includes all necessary files to start a calculation service. One has to copy the hpcservice to your calculation machine or login node of a HPC cluster, which should have the job management system. One needs to check the torquejob.sh if it satisfies your system requirements, and the service can be started with

python webserver.py

Then it returns the port number, and the service url is a combination of hostname and port number (default 8075), for example http://sol10.physik.hu-berlin.de:8075, you should add this to the exciting@web interface for your account. This means that you have exciting@web service provided from one machine, where the results are stored in the eXist database. This web interface can submit exciting jobs to your calculation service, on which the calculation runs. The calculation service provider does not necessarily to be the same machine where you have exciting@web interface installed.


3.6 Submit calulations

After preparing the input and calculation service, you can now go to the Inputs panel and select your file. Each input file has a show/run link which leads to the view of the input file where a submit button is available. After pressing the submit button you will be asked to select the calculation service and pick a job name. Then you can submit the input to the calculation service.


By submitting the calculation the input file is sent to the server and the exciting code is started. The species files are loaded from the internet. In order to make this work the speciespath attribute must be:"http://xml.exciting-code.org/species/".

When the job is successfully started the progress can be surveyed via the Jobs panel and Status page.


Groundstate progress of the calculation can be check from the “info” tab after you click on the “R” status link.


The status of the job is updated lively.


3.7 Import data

After the calculation is finished one can load the data that is on the remote calculation service into the database. For this purpose you will find an import button at the bottom of the jobs info page.


You can see all files with .xml extension are imported from the calculation service into the exciting@web database.


Till now the data should be visible under the Unpublished panel. When the data was successfully imported the job can be deleted. This also deletes the files from the calculation service.

3.8 Upload data

If you want to add exciting results into the database, you can go to the Upload menu on the left side pane. There you can find instruction how to install and use the Xuploarder tool. As a data set consists of a collection of files this is the most convenient way to do this.

3.9 Publish results

Any data set on the Unpublished panel is private.


Next step is to check how good the results are, simply click on the eventual properties tab, i.e. dos, bandstructure.


If everything is fine and you want to put this result into final status and share with other users, you can tick up the check box at the end of this entry, and scroll down to publish selection and press go.


4. Exercise

  1. Upload or copy an input file
  2. Edit and submit
  3. Import the results
  4. Publish only new results

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License