gel.scripts.forward

  1"""The forward model.
  2
  3For all arguments, run `forward --help`
  4
  5Will interact with local file system when run as a command. This
  6includes:
  7* Logs what it is doing in file specified by name `LOG_FILE`
  8* Uses a directory `results_dir` as a super-directory for all forward
  9model results. This directory should be clear of subdirectories except
 10for those created by **specifically this program**.
 11* Creates a .csv file `table.csv` under `results_dir` to store a chart
 12of all options used and some result info like runtime.
 13* Creates a subdirectory under `results_dir` according to the options
 14provided.
 15* In that subdirectory, stores many .xdmf files.
 16* If a subdirectory for a collection of settings already exists, will
 17not proceed forward and quietly skip.
 18"""
 19from gel import *
 20import os
 21from sanity_utils import *
 22
 23
 24LOG_FILE = "log.txt"
 25
 26
 27FORWARD_EXP_COLS = [
 28    "Results Dir",
 29    "Cell Name",
 30    "Formulation",
 31    "Modulus Repr",
 32    "Modulus Ratio",
 33    "pc",
 34    "Load Steps",
 35    "Absolute Tolerance",
 36    "Relative Tolerance",
 37    "Traction",
 38    "lower_bound",
 39    "upper_bound",
 40    "Inner Mesh",
 41    "Outer Mesh",
 42    "u_init",
 43    "time"
 44]
 45"""Names of columns in `table.csv`"""
 46
 47
 48def run_experiments(args):
 49    """Sets up logging to relevant files and starts the forward model.
 50
 51    * `args`: `argparse.Namespace` with parsed command arguments
 52
 53    Side-effects: see intro to `gel.scripts.forward`; does all the file
 54    handling except the experiment's subdirectory
 55
 56    Computation: calls `output_single_forward_result`, which handles
 57    the experiment's subdirectory.
 58    """
 59    logger = get_global_logger(LOG_FILE)
 60
 61    # Results
 62    result_csv_path = os.path.join(args.r, "table.csv")
 63    csv = ResultsCSV(result_csv_path, FORWARD_EXP_COLS)
 64
 65    logger.info(f"Detected number of processes: {MPI.comm_world.Get_size()}")
 66
 67    exp_info = (
 68        args.r,
 69        args.c,
 70        args.f,
 71        args.a,
 72        args.k,
 73        args.p,
 74        args.l,
 75        args.tola,
 76        args.tolr,
 77        args.t,
 78        args.b[0],
 79        args.b[1],
 80        args.bci,
 81        args.bco,
 82        args.u_init
 83    )
 84
 85    logger.info(f"Beginning experiment with arguments {exp_info}.")
 86
 87    # Be careful of it already existing
 88    try:
 89        total_time = output_single_forward_result(*exp_info)
 90
 91        # Update DataFrame
 92        csv.add_row(list(exp_info)+[float(total_time)])
 93
 94        # Save into file
 95        csv.save()
 96    except FileExistsError:
 97        logger.info("Found that directory already exists. Skipping...")
 98
 99
100def output_single_forward_result(
101        results_dir,
102        cell_data_dir,
103        formulation,
104        mod_repr,
105        k,
106        pc,
107        load_steps,
108        tola,
109        tolr,
110        traction,
111        lower_bound,
112        upper_bound,
113        bci,
114        bco,
115        u_init
116    ):
117    r"""Runs a single forward model experiment, writes subdirectory and
118    logs progress.
119
120    * `results_dir`: str path to directory to put all results
121    * `cell_data_dir`: str path to directory with geometry information
122    to use, see the constructor to `gel.geometry.Geometry` for required
123    files
124    * `formulation`: str a valid material model formulation, see
125    `gel.mechanics` for options
126    * `mod_repr`: str a valid modulus representation, see
127    `gel.mechanics` for options
128    * `k`: float $\frac{D_1}{c_1}$ ratio
129    * `pc`: str preconditioner to use, see `gel.gel.ForwardSimulation`
130    for more details
131    * `tola`: float the absolute tolerance for Newton-Raphson
132    * `tolr`: float the relative tolerance for Newton-Raphson
133    * `traction`: str filename to traction if using, see
134    `gel.gel.ForwardSimulation` for details
135    * `lower_bound`: float the lower bound for the "beta_tilde"
136    formulation described in `gel.mechanics`
137    * `upper_bound`: float the upper bound for the "beta_tilde"
138    formulation described in `gel.mechanics`
139    * `bci`: str path to .vtk file with inner BC info, see
140    `gel.geometry.Geometry` for details
141    * `bco`: str path to .vtk file with outer BC info, see
142    `gel.geometry.Geometry` for details
143    * `u_init`: str path to full-shape .xdmf file with initial
144    displacements
145
146    Side-effects: writes many files in new subdirectory to
147    `results_dir`, see intro to `gel.scripts.forward`
148
149    Returns: float time it took to run
150    """
151    # Input validation
152    validate_formulation(formulation)
153    validate_mod_repr_field(mod_repr)
154
155    # Get cell name
156    cell_name = read_cell_name(cell_data_dir)
157
158    # Output directory handling
159    output_dir = prepare_experiment_dir(
160        results_dir,
161        cell_name,
162        formulation,
163        mod_repr,
164        k,
165        pc,
166        load_steps,
167        traction,
168        lower_bound,
169        upper_bound,
170        bci,
171        bco,
172        u_init
173    )
174
175    # Setup logging
176    logger, logger_destructor = create_experiment_logger(output_dir)
177
178    #
179    # Experiment
180    #
181    logger.info(f"Beginning experiment in {formulation} formulation.")
182    logger.info(f"Using cell data from {cell_data_dir}, '{cell_name}'")
183    logger.info(f"Using mod_repr field: {mod_repr}")
184    logger.info(f"Using D1/C1: {k}")
185    logger.info(f"Using preconditioner: {pc}")
186    logger.info(f"Abs tolerance: {tola}")
187    logger.info(f"Rel tolerance: {tolr}")
188    logger.info(f"Traction filename: {traction}")
189    logger.info(f"Using load steps: {load_steps}")
190    logger.info(f"Override inner BC: {bci}")
191    logger.info(f"Override outer BC: {bco}")
192    logger.info(f"Initial displacements: {u_init}")
193
194    # Timer start
195    timer = ExperimentTimer()
196    timer.start()
197
198    # run
199    addn_args = {"bci_data" : bci, "bco_data" : bco}
200    formulation_kwargs = dict()
201    if formulation == "beta_tilde":
202        formulation_kwargs["beta_min"] = lower_bound
203        formulation_kwargs["beta_max"] = upper_bound
204
205    sim = ForwardSimulation(
206        "real_cell_gel",
207        k,
208        formulation=formulation,
209        mod_repr_init=mod_repr,
210        vprint=logger.info,
211        data_directory=cell_data_dir,
212        restrict_ctl_dofs_to_veh=False,
213        pc=pc,
214        load_steps=load_steps,
215        tola=tola,
216        tolr=tolr,
217        traction=traction,
218        u_init=u_init,
219        formulation_kwargs=formulation_kwargs,
220        **addn_args
221    )
222    sim.run_forward()
223    kinematics, mod_repr = sim.kinematics, sim.mod_repr
224
225    # Timer end
226    total_time = timer.end()
227    logger.info(f"Took {total_time} seconds to complete")
228
229    # Save
230    geo = kinematics.geo
231    logger.info(f"Saving results to {output_dir}")
232    kinematics_sim = Kinematics(geo, kinematics.u)
233    output_results_paraview(output_dir, kinematics_sim, mod_repr)
234
235    # Tear down logging
236    logger_destructor()
237
238    return total_time
239
240
241def forward():
242    """The function invoked by the command. Parses arguments and passes
243    to `run_experiments`.
244    """
245    parser = get_common_parser(
246        description="Run the forward model for ground-truth"
247        " simulations of test problems"
248    )
249
250    parser.add_argument(
251        "-r",
252        metavar="RESULTS_DIR",
253        default="forward",
254        help="superdirectory in which all solutions are saved"
255    )
256    parser.add_argument(
257        "--tola",
258        type=float,
259        metavar="ABS_TOL",
260        default=1e-10,
261        help="Newton-Rasphon absolute residual tolerance"
262    )
263    parser.add_argument(
264        "--tolr",
265        type=float,
266        metavar="REL_TOL",
267        default=1e-9,
268        help="Newton-Rasphon relative residual tolerance"
269    )
270    parser.add_argument(
271        "-a",
272        metavar="MOD_REPR",
273        default="zero",
274        help="the modulus field to use"
275    )
276    parser.add_argument(
277        "-t",
278        type=str,
279        metavar="TRACTION",
280        default=None,
281        help="full-shape .xdmf file with 1st order Lagrange reference tractions"
282        " 'T' over the whole gel domain, note that values outside cell surface "
283        "are ignored. 'zero' for automatic 0 traction, but suppress cell BC"
284    )
285    args = parser.parse_args()
286
287    run_experiments(args)
288
289
290if __name__ == "__main__":
291    forward()