camber.athena

The camber.athena.AthenaEngine handles Athena workloads. It uses athena++ for CPU workloads and athenak for GPU workloads.

It is a subclass of CamberEngine, and inherits many of the universal engine methods. This page documents only the overridden or added engine methods specific to the Athena workflow.

Example

from camber.athena import AthenaEngine

engine = AthenaEngine(
	engine_size="LARGE",
	with_gpu=True,
)

# standard chain workflow
engine.build(problem_generator="kh", clean_build=True) \
			.run(input_file="athinput.kh.v1", output_dir="kh-data-v1")

# continue to use the engine with the same binary
engine.run(input_file="athinput.kh.v2", output_dir="kh-data-v2")

# switch gear to cpu
# note in build the -b flag that enables magnetic field for orszag-tang
engine.use_size("LARGE", gpu=False) \
      .use_count(num_engines=3) \
			.build(problem_generator="orszag_tang", clean_build=True, b=True) \
			.run(input_file="athinput.orszag_tang", output_dir="orszag-tang")

Methods

use_athena_home

use_athena_home(self, athena_home: str)

Sets the path to the Athena repository.

Args

athena_home (str)

The path to the Athena repository.

Either be a relative path from the current working directory or an absolute path.

Returns

self

Returns the engine itself with the new Athena home path.

build

Builds the Athena binary executable using AthenaEngine. The Camber platform enforces the following customizations on the Athena binary built using the build method:

• MPI is always enabled
• HDF5 support enabled
• Underlying GPU options are optimized for hardware

Args

problem_generator: Optional[str]

A string specifying the problem generator to use.

clean_build: Optional[bool]

A boolean to specify whether to perform a clean build using make clean.

tags: Optional[Union[str, List[str]]]

An optional parameter that can be a string or a list of strings to tag the build.

dry_run: Optional[bool]

An optional boolean to specify whether to perform a dry run and print the actual command the engine will run.

**kwargs

Additional keyword arguments for custom build options. For athenak, refer to its CMake flags.

For athena++, refer to the configuration flags in the configuration script. For athena++ options, specify the name as key and True as value to use a flag without value. For example, -b becomes b=True if you want to enable magnetic fields.

Returns

self

Returns the engine itself while adding the build job to the history attribute.

run

Runs the Athena binary executable using AthenaEngine. The parameters seek to emulate the binary options provided in the Athena documentation. If the AthenaEngine already built a binary using the build method, athena_binary_path is unneeded.

Args

input_file: str

The file required for the simulation.

output_dir: Optional[str]

A string specifying the directory to store output files. Defaults to the current working directory. Corresponds to the -d flag in binary options.

athena_binary_path: Optional[str]

A string specifying the path to the Athena binary executable. This is unneeded if the AthenaEngine object already built a binary using the build method before. The run method auto-resolves the built binary for its operation. Otherwise, it is recommended to have the Athena binary inside the current working directory and specify the relative path to it from the current working directory.

test_input: Optional[bool]

A boolean to specify whether to test inputs. Corresponds to -n in binary options.

show_config: Optional[bool]

A boolean to decide whether to display the current Athena binary configuration. Corresponds to -c in binary options.

tags: Optional[Union[str, List[str]]]

An optional parameter that can be a string or a list of strings to tag the run.

dry_run: Optional[bool]

An optional boolean to specify whether to perform a dry run and print the actual command the engine will run.

Returns

self

Returns the engine itself while adding the run job to the history attribute.

create_job

Creates a job using the AthenaEngine that runs the provided command.

Args

command: str

A string representing the command to be executed by the job.

tags: Optional[Union[str, List[str]]]

An optional string or a list of strings to tag the job for easier identification and filtering.

Returns

CamberJob

An instance of the CamberJob class representing the created job.