Running OpenFTS ================== There are two ways to run OpenFTS. 1. Running :ref:`OpenFTS as a python module` 2. Running :ref:`OpenFTS as a C++ executable` Your choice will depend on your workflow and preferences. Converting between the two options is easy (see :ref:`convert_json_python`). If you're in doubt, try :ref:`openfts_python`, it is much more powerful and will allow you to develop much more flexible and powerful workflows using OpenFTS. One situation where :ref:`openfts_c++` 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 `_ .. _openfts_python: 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=/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(cell_scale=1.0,cell_lengths=[4.3],dimension=1,length_unit='Rg') fts.driver(dt=5.0,nsteps=4000,output_freq=100,type='SCFT',stop_tolerance=1e-05,) fts.field_updater(type='EMPEC',update_order='simultaneous',adaptive_timestep=False,lambdas=[1.0, 1.0]) fts.field_layout(npw=[64],random_seed=1) fts.model(Nref=1.0,bref=1.0,chiN=20.,type='MeltChiAB') fts.init_model_field(height=1.0,ngaussian=1,type='gaussians',width=0.1,centers=[0],fieldname='mu_minus') fts.init_model_field(type='random',mean=0.0,stdev=1.0,fieldname='mu_plus') fts.add_molecule(alpha=1.0,ds=0.01,nblocks=2,block_fractions=[0.5, 0.5],block_species=['A', 'B'],type='PolymerLinear',chain_type='continuous,volume_frac=1.0) fts.add_operator(averaging_type='none',type='Hamiltonian') fts.add_operator(averaging_type='none',type='CellStress') fts.output_default() fts.add_species(label='A',stat_segment_length=1.0) fts.add_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 :ref:`Setting up a simulation`, so don't worry if you don't understand what each line means yet. By default OpenFTS executes in serial on the CPU with double precision. Other execution options can be enabled by issuing :: # serial cpu, single fts.runtime_mode('serial') fts.runtime_precision('single') # gpu, double fts.runtime_mode('gpu') fts.runtime_precision('double') .. note:: Don't forget to recompile OpenFTS using the `ENABLE_GPU` or `SINGLE_PRECISON_FIELDS` cmake flags as needed. .. 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 :ref:`Python Module API`. .. If you're curious about what is going on behind the scenes in the python module, all of the lines in the first code block above are simply populating an internal dictionary data structure within the `fts` instance of a python `OpenFTS` object. The final `fts.run()` command then converts this dict to json and then passes this json data structure into the C++ OpenFTS library using pybind11. This is essentially identical to what is happening when running `OpenFTS_serial_dp.x input.json` line in the C++ executable. .. _openfts_c++: 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:: /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:: /build/src/OpenFTS_serial_sp.x input.json # execute on serial cpu, single precision /build/src/OpenFTS_gpu_dp.x input.json # execute on gpu, double precision /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 `. This makes modifying files much simpler than using find/replaces using `sed`. Check it out! .. _convert_json_python: 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. Json to python ^^^^^^^^^^^^^^^ If you're starting from an `input.json` file, you can generate a python script using the command:: $ /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 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:: /OpenFTS_serial_dp.x input.json