Tutorials

The several cases in the Tests/test_files directory are a good starting point for setting up new cases. In addition, there are several tutorials from AMReX that may be useful for general familiarity with how to build and run AMReX codes.

Running a First Simulation

This short tutorial demonstrates how to execute a 2D flow around a single cylinder and how to inspect the output.

  1. Compile MARBLES: Follow the compilation instructions in the Building section to generate the marbles executable.

  2. Navigate to the Test Directory: Change into the single cylinder test directory.

    cd Tests/test_files/single_cylinder

  3. Execute the Simulation: Run the executable using MPI, passing the input file as an argument. Adjust the path to where your compiled executable is located.

    mpirun -np 4 ../../../marbles single_cylinder.inp

  4. Monitor the Output: As the simulation runs, MARBLES will print step information and create plotfiles continuously (e.g., plt00000, plt00010, etc.) at the intervals specified by the amr.plot_int parameter in the input file.

Visualization with ParaView or VisIt

The output directories generated by MARBLES (the pltXXXXX folders) are AMReX format plotfiles. They contain the mesh grid data, state variables (like density, velocity magnitude, temperature), and the embedded boundary geometry representation.

Using ParaView: ParaView has built-in support for reading AMReX plotfiles.

  1. Open ParaView.

  2. Go to File > Open, navigate to the output folder, and enter the pltXXXXX directory.

  3. Select the Header file inside it. (Alternatively, ParaView may let you open the folder directly as AMReX/BoxLib).

  4. In the Properties panel, click Apply.

  5. You can now select variables like vel_mag or density from the drop-down menu to view using pseudocolor plots, slice the domain, or generate contours around the embedded geometry.

Using VisIt: VisIt also natively reads AMReX plotfiles.

  1. Open VisIt.

  2. Click Open, navigate to your test directory, and select the Header file within the pltXXXXX folder.

  3. Add a Pseudocolor plot for a variable like vel_mag and click Draw.

Quantitative Data Analysis with Post-Processing Tools

For many validation configurations, MARBLES includes Python tools and Jupyter notebooks to analyze output and post-process the physical quantities analytically.

For example, in the Sod Shock Tube test:

  1. Run the simulation in Tests/test_files/sod/.

  2. Navigate to the Tools/sod_test/ directory.

  3. Launch the provided Jupyter notebook:

    jupyter notebook sod_test.ipynb

  4. The notebook contains Python scripts utilizing common scientific packages (like numpy, scipy, matplotlib) to extract 1D profiles of density, velocity, and pressure from the simulation and compares them directly to the exact analytical Sod shock tube solution.

Other scripts in the Tools/ directory (such as viscosity_test/viscosity_tester.ipynb and thermaldiffusivity_test/thermaldiffusivity_tester.ipynb) serve as an excellent starting point for building custom Python data extraction and validation scripts for your own setups.