Setting up FusionSC
Setting up component lookup (version 2.2 and above)
While FusionSC can be used out of the box (import fusionsc as fsc), it doesn’t bundle the part and coil geometries (partly due to size, partly to comply with data access policies). In order to run FusionSC with pre-defined geometries, the resolution subsystem needs to be hooked up with lookup tables / storage for these devices.
The recommended way (available from version 2.2 onwards) is to use the user configuration file in “~/.fusionsc.yaml” (an alternative path can be specified by setting the FUSIONSC_CONFIG_PATH environment variable). The “fusionsc-config” command line (alternatively usable via “python -m fusionsc.config”) can be used to manage this configuration file.
Wendelstein 7-X inside IPP network
Use the “ipp-hgw” default profile, which will connect to a compute server and rely on the resolution database stored there.
fusionsc-config default ipp-hgw
FZJ network
Use the “fzj” default profile, which will connect to a compute server and rely on the resolution database stored there.
fusionsc-config default fzj
J-TEXT
Simplified J-TEXT geometries are bundled with FusionSC. No further configuration is required to use them.
Others
You will have to manually add the neccessary resolution files. Usually this entails adding them with the config tool
fusionsc-config resolve add {file or url}
What if ‘fusionsc-config’ can not be found
In a lot of python installations (environments, the py launcher) only the python executable is on the command line path, but not scripts like “jupyter” or “fusionsc-config”. In this case, you can also call the configuration CLI as a python module instead of calling “fusionsc-fonfig”:
python -m fusionsc.config ...
Setting up component lookup with python methods (version 2.0 and above)
For version 2.1 and below, and if you don’t want to rely on the user configuration, you can always use the methods fusionsc.resolve.importOfflineData and fusionsc.resolve.connectWarehouse. Keep in mind that the changes by these methods are local to the current context.
Wendelstein 7-X inside IPP network
On version 2.1 and above, you can use the fusionsc.devices.w7x.connectIppSite method to configure the computing server and resolution database, similar to the “ipp-hgw” configuration default profile.
from fusionsc.devices import w7x
w7x.connectIppSite()
Original Coils- and Components-DB
FusionSC uses a binary variant of the Coils- and Components-DB, which is periodically mirrored from the original webservices. If that mirror becomes stale or unavailable, you can also instruct FusionSC to download coils & components from the original CoilsDB and ComponentsDB webservices. This will be slow
from fusionsc.devices import w7x
w7x.connectLegacyIPPSite()
(W7-X only) Pre-calculating fields for Biot-Savart calculation
A generally expensive calculation is the Biot-Savart rule to obtain the magnetic field from the coil geometries. For W7-X , there is a high-level support to precompute the coil fields. These fields can then be saved and loaded later for usage. When using precomputed coil fields, the offline data files are not required (unless required for other reasons, such as geometry data or other field information). W7-X has special support to pre-compute all coils so that they can be re-used later.
The precomputation is performed through the devices.w7x.CoilPack class, which can be used as a handle to override the coils
used in the generation of W7-X configurations.
from fusionsc.devices import w7x
# Obtain default coils
coils = w7x.cadCoils()
# Compute
coils = coils.computeFields(w7x.defaultGrid())
# Use in configuration
config1 = w7x.standard(coils = coils)
config2 = w7x.highIota(coils = coils)
The precalculated fields can be saved and loaded like other field or geometry classes.
# Save
coils.save("coils.fsc")
# Restore
coils = w7x.CoilPack.load("coils.fsc")
(Re-)Configuring the local backend
While fusionsc is capable of connecting to remote servers for execution and data management, by default it uses a local backend started at import time. The backend is started with a default configuration (all services enabled, CPU execution, auto-detected no. of computation threads). Sometimes it is desirable to override this default behavior. You can use the backends.reconfigureLocalBackend function for this purpose.
Note: This function creates a new backend to be used by all future calls. The old backend will be closed once all references to it coming from previous pending calls are dropped. If the local backend has been exposed (e.g. as a network service or by storing the result of backends.activeBackend) it will not shut down until these external references are dropped as well.
# Get default configuration
config = fsc.service.LocalConfig.newMessage()
print(' --- Default configuration --- ')
print()
print(config)
print()
# Adjust configuration
config.cpuBackend.numThreads.fixed = 2
print(' --- Adjusted configuration --- ')
print()
print(config)
print()
# Apply adjusted configuration
fsc.backends.reconfigureLocalBackend(config)
--- Default configuration ---
preferredDeviceType: cpu
enableCompute: true
enableStorage: true
jobScheduler: system
flt:
eventBuffer:
minSize: 100
maxSize: 2500
targetTotalMb: 500
cpuBackend:
numThreads: autoDetect
--- Adjusted configuration ---
preferredDeviceType: cpu
enableCompute: true
enableStorage: true
jobScheduler: system
flt:
eventBuffer:
minSize: 100
maxSize: 2500
targetTotalMb: 500
cpuBackend:
numThreads:
fixed: 2
Using verbose logging
Sometimes it is desirable to enable the internal log output to see progress on the calculation. This can be achieved by setting the FUSIONSC_VERBOSE environment variable to any other value than 0. This has to be done before importing the package.
import os
os.environ['FUSIONSC_VERBOSE'] = '1'
import fusionsc as fsc
When using the standalone server, verbose logging can be activated through the --verbose command-line switch.
The user configuration (frontend configuration)
Shown below is an example configuration file that shows you, which settings you can adapt. Every single configuration option is optional. FusionSC will look for such a file under ~/.fusionsc.yaml (oder under FUSIONSC_CONFIG_PATH if that environment variable is set).
The user configuration below is just a rough example. It is not a valid default configuration file, do not just copy it into your home folder.
backend: http://path-to-remote-backend
# Use this setting to use a remove backend for calculation and gain access to the warehouse databases stored there.
resolve:
# This setting controls data sources for resolution of machine components and coils.
# Put references to local archive files, as well as local and remote warehouses here.
# The URL scheme "remote:" can be used to access warehouses in the "warehouses" entry
# of the backend configuration.
- warehouse: sqlite:///path/to/local/warehouse.db
- warehouse: "sqlite:///path/to/local/warehouse.db#path/to/entry"
- warehouse: http://remote-warehouse
- warehouse: remote:warehouse-on-backend
- archive: /path/to/local/archive.fsc
w7x:
# This setting contains configuration options for the Wendelstein 7-X module
- defaultCoilsUrl: "{warehouse URL}#path/to/coil/entry"
# When specified, FusionSC will use the coil pack stored here (as a W7XCoilPack struct) as the default coil set
# for all W7-X configurations (if no coil pack is specified in the code).
# When not specified, it uses the default W7-X coils in the components DB.
localBackend:
# In here, you can override the default settings for the local backend. The local backend will
# always be available under fsc.backends.localBackend(), but will only be used by the frontend
# if the backend setting above is not specified.
The backend configuration
The compute backend has its own configuration settings. Below is a full rundown of the complete backend configuration. You can put this setting as the localBackend entry in the user configuration (when configuring the local backend on the client) or pass it to the fusionsc server command (either as a file or on its standard input stream). Note that this file corresponds to the LocalConfig struct defined in service.capnp
name: "FusionSC Server"
# A human-readable display name
preferredDeviceType: "cpu"
# The preferred device to schedule on if possible. Options are "cpu", "gpu", and "loop" for running compute jobs directly in the main backend thread (mainly for testing).
enableCompute: true
# Whether clients should be able to call compute tasks on this backend. Set this to "false" for nodes that should only
# launch remote compute tasks.
enableStorage: true
# Whether this backend should be allowed to create intermediate storage buffers (such as caches)
jobScheduler: system
# The main scheduler type to be used for launching external compute tasks. Possible values are:
# - system: Launch tasks via command line
# - mpi: Launch tasks via command line wrapped in "mpiexec" (unsupported at the moment)
# - slurm: Launch tasks through slurm (unsupported at the moment)
jobDir: .
# A temporary directory that input and output files for external codes can be written into.
cpuBackend:
# Configuration for the multi-threaded CPU compute device (the main workhorse)
numThreads:
# The number of threads to use for the CPU backend. Either set this to "autoDetect" to use std::hardware_concurrency(),
# or indicate "fixed: {number}: to use a fixed number of threads. Use exactly one of the options below.
autoDetect
# fixed: 1
workerLauncher: ~
# Reserved option for a work-in-progress system to launch worker nodes on-demand. This system is not yet ready for client use.
loadLimit: 100
# Maximum number of concurrently active jobs. Jobs exceeding this number will be held in a waiting queue.
warehouses:
# FusionSC allows the backend to host warehouses (both read-only and read-write) that can be accessed on the client.
# When connected to a backend that uses this option, these warehouses can be navigated through the "remote:{entry name}" URL
# scheme on the client syde (python-only feature). When data stored in such a warehouse are passed by reference to the backend
# (e.g. to the DataRef mechanism, which is extensively employed by the resolution engine), then data round-trips from the backend
# to the client and back are completely avoided, and the data flow is handled by the backend completely. This can avoid a lot of
# unneccessary data transfer between client and server.
- name: main-data
url: sqlite:///path/to/local?read-only
- name: user-data
url: sqlite:///path/to/user
flt:
# Configuration for the field line tracing engine.
defaultStepLimit: 0
# A step count limit that can be applied if no user-specified limits are requested.
maxStepLimit: 0
# A hard step limit that can be enforced to prevent infinite runs. Note that this setting might cause jobs to
# be hard-terminated instead of returning a stop code for the specific field line.
eventBuffer:
# FusionSC uses a pre-allocated buffer to record event streams (such as turn count changes, plane- and geometry intersections).
# in order to be compatible with GPU backends. These settings control the allocation strategy for the buffer. FusionSC will not
# fail when running out of buffer space (as it uses a multi-round scheduler), but an excessively small buffer will cause many
# calls to the backend kernel to be made.
minSize: 100
maxSize: 2500
# Minimum and maximum number of events per field line (and computation round) in the buffer.
targetTotalMb: 500
# The total buffer size to aim for when creating the compute buffer for a single round.
vmec:
# Configuration of the VMEC driver
command: "xvmec2000"
# The command to run VMEC. Is passed to the OS shell (or rather, the chosen process launcher) as command, so it can be either
# an executable on your PATH or an absolute filename.
Environment variables
FusionSC uses the following environment variables:
Variable |
Description |
|---|---|
FUSIONSC_KEEP_JOB_DIRS |
Set this to anything other than |
FUSIONSC_RAM_OBJECT_LIMIT |
Maximum size (in bytes) of objects to be stored in RAM by the data service. Larger objects are saved in file-backed memory to enable faster swapping of the memory. Defaults to 500MB. |
FUSIONSC_VERBOSE |
Set this to anything other than |