From ea4bd0e2c6f174679dc09169f3f234de0c199daf Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 4 Mar 2015 10:30:27 -0600 Subject: [PATCH] Explain the use of operator| for the update_* flags. --- examples/step-3/step-3.cc | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/examples/step-3/step-3.cc b/examples/step-3/step-3.cc index 2b89cefb47..bc7faaa162 100644 --- a/examples/step-3/step-3.cc +++ b/examples/step-3/step-3.cc @@ -1,6 +1,6 @@ /* --------------------------------------------------------------------- * - * Copyright (C) 1999 - 2014 by the deal.II authors + * Copyright (C) 1999 - 2015 by the deal.II authors * * This file is part of the deal.II library. * @@ -307,6 +307,39 @@ void Step3::assemble_system () // compared to approaches where everything, including second derivatives, // normal vectors to cells, etc are computed on each cell, regardless of // whether they are needed or not. + // + // @note The syntax update_values | update_gradients | + // update_JxW_values is not immediately obvious to anyone not + // used to programming bit operations in C for years already. First, + // operator| is the bitwise or operator, i.e., + // it takes two integer arguments that are interpreted as bit + // patterns and returns an integer in which every bit is set for + // which the corresponding bit is set in at least one of the two + // arguments. For example, consider the operation + // 9|10. In binary, 9=0b1001 (where the + // prefix 0b indicates that the number is to be + // interpreted as a binary number) and 10=0b1010. Going + // through each bit and seeing whether it is set in one of the + // argument, we arrive at 0b1001|0b1010=0b1011 or, in + // decimal notation, 9|10=11. The second piece of + // information you need to know is that the various + // update_* flags are all integers that have exactly + // one bit set. For example, assume that + // update_values=0b00001=1, + // update_gradients=0b00010=2, + // update_JxW_values=0b10000=16. Then + // update_values | update_gradients | update_JxW_values = + // 0b10011 = 19. In other words, we obtain a number that + // encodes a binary mask representing all of the operations you + // want to happen, where each operation corresponds to exactly + // one bit in the integer that, if equal to one, means that a + // particular piece should be updated on each cell and, if it is + // zero, means that we need not compute it. In other words, even + // though operator| is the bitwise OR operation, + // what it really represents is I want this AND that AND the + // other. Such binary masks are quite common in C programming, + // but maybe not so in higher level languages like C++, but serve + // the current purpose quite well. // For use further down below, we define two shortcuts for values that will // be used very frequently. First, an abbreviation for the number of degrees -- 2.39.5