Skip to content
A plugin to run a EasyVVUQ campaign using FabSim3
Branch: master
Clone or download
Pull request Compare This branch is 84 commits ahead, 4 commits behind djgroen:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config_files/dummy_test
examples
templates
.gitignore
FabUQCampaign.py
LICENSE
README.md
Tutorial_ocean.md

README.md

FabUQCampaign

This plugin runs the samples from an EasyVVUQ campaign using FabSim3 via the campaign2ensemble subroutine.

Installation

Simply type fab localhost install_plugin:FabUQCampaign anywhere inside your FabSim3 install directory.

Explanation of files

  • FabUQCampaign/FabUQCampaign.py: contains the run_UQ_sample subroutine in which the job properties are specified, e.g. number of cores, memory, wall-time limit etc
  • FabUQCampaign/templates/run_UQ_sample: contains the command-line execution command for a single EasyVVUQ sample.
  • FabUQCampaign/examples/advection_diffusion/: an example script, see below.

Detailed Examples

Executing an ensemble job on localhost

In the examples folder there is a script which runs an EasyVVUQ Stochastic Collocation (SC) campaign using FabSim3 for a simple advection-diffusion equation (ade) finite-element solver on the localhost. The governing equations are:

equation,

where the Peclet Number (Pe) and forcing term (f) are the uncertain SC parameters, and u is the velocity subject to Dirichlet boundary conditions u(0)=u(1)=0. The script executes the ensemble using FabSim, computes the first two moments of the output, generates some random sample of the SC surrogate and computes the first-order Sobol indices of Pe and f.

The file run_SC_Fab_campaign.py contains the main script. The first 4 steps are the same as for an EasyVVUQ campaign that does not use FabSim to execute the runs:

  1. Create an EasyVVUQ campaign object, with ade_input.json as argument, which defines the UQ campaign: my_campaign = uq.Campaign(state_filename=input_json)
  2. Per uncertain parameter, select the input distribution via Chaospy, e.g. my_campaign.vary_param("Pe", dist=cp.distributions.Uniform(-1, 1))
  3. Select the SC_Sampler (and specify the polynomial order p), which creates a tensor grid from the 1D rules selected in step 2: sc_sampler = uq.elements.sampling.SCSampler(my_campaign, p), and add the runs via my_campaign.add_runs(sc_sampler, max_num=number_of_samples). The number_of_samples variable is simply the number of points in the tensor grid.
  4. Create the ensemble run directories which will be used in FabSim's campaign2ensemble subroutine: my_campaign.populate_runs_dir()

Only the fifth step is specific to FabSim. For now, several variables need to be hardcoded, i.e.:

  • A simulation identifier ($sim_ID)
  • Your FabSim home directory ($fab_home)
  • The FabUQCampaign/template/run_UQ_sample file contains the command line instruction to run a single sample, in this case: python3 $ade_exec ade_in.json. Here, ade_in.json is just the input file with the parameter values generated by EasyVVUQ. Furthermore, $ade_exec is the full path to the Python script which runs the advection diffusion equation at the parameters of ade_in.json. It is defined in deploy/machines_user.yml, which in this case looks like

localhost:

    ade_exec: "$fab_home/plugins/FabUQCampaign/examples/advection_diffusion/run_ADE.py"

The following two commands execute the ensemble run:

  1. cd $fab_home && fab localhost campaign2ensemble:$sim_ID, campaign_dir=$campaign_dir
  2. cd $fab_home && fab localhost uq_ensemble:$sim_ID

The run directory $campaign_dir is available from the EasyVVUQ object. The campaign2ensemble results directory (located in ~/FanSim3/results) has (by design) the same structure as the EasyVVUQ run directory, so the results can simply be copied back, in this case via

cp -r ~/FabSim3/results/ade_example1_localhost_16/RUNS/Run_* $campaign_dir/runs

Afterwards, post-processing tasks in EasyVVUQ can be undertaken, by creating a SCAnalysis object: sc_analysis = uq.elements.analysis.SCAnalysis(my_campaign, value_cols=output_columns). Here, output_columns is the name of the column in the output CSV file containing the simulation results (u(x) in this case).

  • To compute the mean and variance of the output use: sc_analysis.get_moments(p).

  • To generate a random output sample from the SC surrogate, use sc_analysis.surrogate(xi), where xi is a random Monte Carlo input sample.

  • To compute the Sobol indices from the SC samples, use: sc_analysis.get_Sobol_indices(typ), where typ can be 'first_order' or 'all'.

Executing an ensemble job on a remote host

To run the example script on a remote host, every instance of localhost must replaced by the machine_name of the remote host. Ensure the host is defined in machines.yml, and the user login information and $ade_exec in deploy/machines_user.yml.

You can’t perform that action at this time.