2. Running OpenFTS

There are two ways to run OpenFTS.

  1. Running OpenFTS as a python module

  2. Running OpenFTS as a C++ executable

Your choice will depend on your workflow and preferences. Converting between the two options is easy (see Converting between json and python input files). If you’re in doubt, try OpenFTS as a python module, it is much more powerful and will allow you to develop much more flexible and powerful workflows using OpenFTS.

One situation where OpenFTS as a C++ executable is preferred is if you are developing new functionality in OpenFTS (i.e. changing the source code, debuging, profiling, etc). In this case, it can be easier to work directly with a C++ executable and use tools like gdb or valgrind. This lets you get “closer to the ground” and can avoid python-related issues.

Attention

In order to run OpenFTS you need a valid license_key file located in the OpenFTS root directory. If you don’t have one, contact contact Joshua Lequieu

2.1. OpenFTS as a python module

The preferred option for running OpenFTS is to use it as a python module. To use this option, make sure that OpenFTS was built using the cmake option -DBUILD_PYBIND=ON (this is the default). This option will create a new directory containing a new openfts python module in build/python/. To load this module, you will need to update the PYTHONPATH environment variable:

$ export PYTHONPATH=<path>/build/python:${PYTHONPATH}

Confirm that python can load this module by running:

$ python3 -c "import openfts; fts = openfts.OpenFTS()"

You can now run OpenFTS from directly from within a python script. To do this, you first need to setup the parameters needed for OpenFTS (comparable to creating the input.json file when running as a C++ executable). For example, setting up these parameters for a diblock melt can be achieved using

import openfts

fts = openfts.OpenFTS()

fts.cell = openfts.Cell(cell_scale=1.0,cell_lengths=[4.3],dimension=1,length_unit='Rg')
scft = openfts.driver.SCFT(dt=5.0,nsteps=4000,output_freq=100,stop_tolerance=1e-05,)
empec = openfts.field_updater.EMPEC(update_order='simultaneous',
                                    adaptive_timestep=False,lambdas=[1.0, 1.0])
scft.field_updater = empec
fts.driver = scft

fts.field_layout = openfts.FieldLayout(npw=[64],random_seed=1)
chiAB = openfts.model.ChiAB(Nref=1.0,bref=1.0,chiN=20.)

chiAB.init_fields['mu_minus'] = openfts.init_field.Gaussian(height=1.0,ngaussian=1,
                                                            width=0.1,centers=[0])
chiAB.init_fields['mu_plus'] = openfts.init_field.Random(mean=0.0,stdev=1.0)
fts.model = chiAB

mol0 = openfts.molecule.PolymerLinearContinuous(alpha=1.0,ds=0.01,nblocks=2,volume_frac=1.0,
                                                block_species=['A', 'B'],block_fractions=[0.5, 0.5])
fts.molecules.append(mol0)

fts.operators.append(openfts.operator.Hamiltonian(averaging_type='none'))
fts.operators.append(openfts.operator.CellStress(averaging_type='none'))

fts.output = openfts.Output()

fts.species.append(openfts.Species(label='A',stat_segment_length=1.0))
fts.species.append(openfts.Species(label='B',stat_segment_length=1.0))

Finally OpenFTS can be run by adding the final line to your python script:

fts.run()

A description of all of these different input parameters is described in Setting up a simulation, so don’t worry if you don’t understand what each line means yet.

OpenFTS will choose to execute using the SERIAL/OMP/CUDA/HIP backend depending on the flags used wwhen OpenFTS was compiled and what hardware is detected. If you want to manually specify a backend you can either:

  1. Pass the backend argument to FieldLayout. This should be SERIAL/OMP/CUDA/HIP.

  2. Set the FIELDLIB_BACKEND environmenal variable (e.g. export FIELDLIB_BACKEND=CUDA)

Note

Many example python scripts can be found in the examples/ directory and look for files named example_*py or run-openfts.py. This is probably the best place to start if you’re new to the code.

For more documentation on the OpenFTS python module see the OpenFTS.

2.2. OpenFTS as a C++ executable

An alternative way to run OpenFTS is as a C++ executable. Running After building the code, a executable OpenFTS_serial_dp.x executable will be created in the build/src/ directory. OpenFTS can be run from the command line as:

<path>/build/src/OpenFTS_serial_dp.x input.json

where input.json is an input json file that contains the parameters needed to run OpenFTS. Take a look in test/unit-tests/test_data/ for the various examples of valid json files.

If you compiled OpenFTS with the ENABLE_GPU or with SINGLE_PRECISON_FIELDS then the executable name should be changed accordingly:

<path>/build/src/OpenFTS_serial_sp.x input.json    # execute on serial cpu, single precision
<path>/build/src/OpenFTS_gpu_dp.x input.json       # execute on gpu, double precision
<path>/build/src/OpenFTS_gpu_sp.x input.json       # execute on gpu, single precision

Note

.json files can easily be read/written/modified using the python json module <https://docs.python.org/3/library/json.html>`. This makes modifying files much simpler than using find/replaces using sed. Check it out!

2.3. Converting between json and python input files

Its easy to convert between the json input files needed to run with the C++ executable and a python script.

2.3.1. Json to python

If you’re starting from an input.json file, you can generate a python script using the command:

$ <path>/OpenFTS/python/tools/json_to_python.py input.json run.py

This will generate a new file run.py that can be used to run OpenFTS as a python module

2.3.2. Python to json

If you’re starting from a python script, you can generate the corresponding input.json file by using the write_json() method from within python

import openfts
fts = openfts.OpenFTS()
... # initialize fts object
fts.write_json('input.json')

This will generate a new file input.json which can be run via:

<path>/OpenFTS_serial_dp.x input.json