1. User-Defined Functions & Subroutines Part 1 Outline

Transcription

1 User-Defined Functions Subroutines Part 1 Outline 1. User-Defined Functions Subroutines Part 1 Outline 2. Intrinsic Functions Are Not Enough 3. User-Defined Functions 4. A User-Defined Function for Mean 5. Flowchart for Mean Function 6. User-Defined Function Definitions 7. User-Defined Function Definitions: Declarations Are Valid Only Within the Unit Where They Occur 8. User-Defined Function Definitions: FUNCTION and END FUNCTION Statements 9. User-Defined Function Definitions: Return Type 10. User-Defined Function Definitions: List of Arguments 11. User-Defined Function Definitions: INTENT Attribute 12. User-Defined Function Definitions: Argument Order for Arrays 13. User-Defined Function Definitions: Local Variables Named Constants 14. User-Defined Function Definitions: Assigning a Return Value to the Return Variable 15. An Important Point About Declarations Inside Functions 16. General Form of User-Defined Function Definitions 17. Using a User-Defined Function: Example 18. Using a User-Defined Function: Example Run 19. Jargon: Program Unit Function Unit 20. Another User-Defined Function Example 21. Using a User-Defined Function: Example #1 22. The EXTERNAL Declaration 23. Actual Arguments Formal Arguments 24. Using a User-Defined Function Example #2: Array Intrinsic Functions Are Not Enough Often, we have a particular kind of value that we need to calculate over and over again, under a variety of circumstances. For example, in our recent project, we had to calculate the mean, variance and standard deviation, which are common functions that come up in a lot of contexts: OU_opponent_score_sum = 0.0 DO game = first_game, number_of_games OU_opponent_score_sum = OU_opponent_score_sum + OU_opponent_score(game) END DO!! game = first_game, number_of_games OU_opponent_score_mean = OU_opponent_score_sum / number_of_games We know that the mean calculation is always the same. So why should we have to write the same piece of code over and over and over and over and over? Wouldn t it be better if we could write that piece of code just once and then reuse it in many applications? See Programming in Fortran 90/95, 1st or 2nd edition, Chapter

2 User-Defined Functions So, it d be nice to replace the code OU_opponent_score_sum = 0.0 DO game = first_game, number_of_games OU_opponent_score_sum = OU_opponent_score_sum + OU_opponent_score(game) END DO!! game = first_game, number_of_games OU_opponent_score_mean = OU_opponent_score_sum / number_of_games with calls to a function that would calculate the mean for any array: OU_opponent_score_mean = mean(ou_opponent_score_value, number_of_games) Obviously, the designers of Fortran 90 weren t able to anticipate the zillion things that we might need functions to do such as calculate the mean so there are no intrinsic functions to calculate things that are somewhat more application-specific. Instead, we as Fortran 90 programmers are going to have to define our own function to do it. A User-Defined Function for Mean REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) Because we as users of Fortran 90 define this kind of function our own personal selves, this kind of function is referred to as a userdefined function. 3 4

3 array, length Start # elements < 1 Initialize sum Initialize index index <= # elts True Increase sum Increment index Flowchart for Mean Function Error message Divide sum Return Stop mean User-Defined Function Definitions REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) In general, the definition of a user-defined function looks an awful lot like a program, except for the following things: 1. FUNCTION and END FUNCTION statements replace the PROGRAM and END PROGRAM statements of a program. 2. The FUNCTION statement begins with a return type. 3. At the end of the FUNCTION statement is a list of arguments, enclosed in parentheses and separated by commas. 4. In the declaration section of the function, each argument must be declared and have an extra attribute called an intent attribute. 5. In addition, the function may declare local named constants and local variables. 6. In the body of the function, the function name is used exactly as if it were a variable and must be assigned a value. 5 6

4 User-Defined Function Definitions: Declarations Are Valid Only Within the Unit Where They Occur REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) A unit is either the main program or a function definition. (We ll see other kinds of units later.) The compiler treats each unit completely independently of the others. Most importantly, the declarations within a unit apply only to that unit, not to any others. For example, the declaration of initial sum in the function mean is visible only to the function mean and not to the main program or to any other function. 7 User-Defined Function Definitions: FUNCTION and END FUNCTION Statements REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) In a function definition, the keyword PROGRAM is replaced by the keyword FUNCTION. So, a function definition has a FUNCTION statement and an END FUNCTION statement, which are analogous to a program s PROGRAM statement and END PROGRAM statement. 8

5 User-Defined Function Definitions: Return Type REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) In the FUNCTION statement, immediately before the keyword FUNCTION is a data type. This data type specifies the return type, which is the data type of the value that the function will return. The return type must be a basic scalar type (e.g., INTEGER, REAL, LOGICAL, CHARACTER). Notice that the return type of the function is not declared in the traditional way, but is declared nonetheless. 9 User-Defined Function Definitions: List of Arguments REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) At the end of the FUNCTION statement, immediately after the function name, is a list of arguments, enclosed in parentheses and separated by commas (just as in a mathematical function definition). The names of these arguments do not have to match the names of the arguments that are passed into the function by the program (or other function) that calls the function. They should be meaningful with respect to the function, not with respect to the program(s) that call the function. 10

6 User-Defined Function Definitions: INTENT Attribute REAL,DIMENSION(number_of_elements), INTENT(IN) :: array In the function s declaration section, each argument must be declared exactly as if it were a variable, except that it must have an additional intent attribute. The intent attribute gives the compiler important information about how the argument is to be used; specifically: whether the argument already has a value when it is passed into the function; whether the function will try to set or change the argument s value. 1. INTENT(IN): (a) the argument does already have a value when it is passed into the function; (b) the function will not try to change the argument s value. 2. INTENT(OUT): (a) the argument does not already have a value when it is passed into the function; (b) the function will set the argument s value. 3. INTENT(INOUT): (a) the argument may already have a value when it is passed into the function; (b) the function may change the argument s value. User-Defined Function Definitions: Argument Order for Arrays REAL,DIMENSION(number_of_elements), INTENT(IN) :: array When using an array argument, you must also use an argument that represents the length of the array. Not surprisingly, this argument should: 1. be of type INTEGER, and 2. have INTENT(IN), since the length of the array should not change inside the function. Notice that, in a sense, giving an argument the INTENT(IN) attribute indicates that the argument s value will not change within the function that is, the argument is constant with respect to the function (though not necessarily with respect to the main program)

7 User-Defined Function Definitions: Local Variables Named Constants REAL,DIMENSION(number_of_elements), INTENT(IN) :: array The function s declaration section may contain, in addition to declarations for the functions arguments, declarations of local named constants and local variables. These names that are valid ONLY within the function that is being defined. On the other hand, these same names can be used with totally different meanings by other functions (and by the calling program). Good programming style requires declaring: 1. arguments first, followed by 2. local named constants, followed by 3. local variables. User-Defined Function Definitions: Assigning a Return Value to the Return Variable REAL,DIMENSION(number_of_elements), INTENT(IN) :: array IF (number_of_elements < minimum_number_of_elements) THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", END IF!! (number_of_elements < min) In the body of the function, the name of the function is used exactly as if it were a variable, and it must be assigned the value that the function is to return. Therefore, it s referred to as the return variable. If the return variable is not assigned a value, the compiler gets upset

8 An Important Point About Declarations Inside Functions The following point is EXTREMELY important: The only symbolic names that a given unit (i.e., program unit or function unit) is aware of are those that are explicitly declared in the unit s declaration section. Thus, the unit is aware of: 1. its arguments (if it is a function); 2. its local named constants; 3. its local variables; 4. other functions that it has declared as EXTERNAL (described later). General Form of User-Defined Function Definitions returntype FUNCTION funcname ( arg1, arg2, ) arg1type, arg1attributes,intent( arg1intent ) :: arg1 arg2type, arg2attributes,intent( arg2intent ) :: arg2 localconst1type,parameter :: localconst1 localconst2type,parameter :: localconst2 localvar1type, localvar1attributes :: localvar1 localvar2type, localvar2attributes :: localvar2 [ function body: does stuff ] funcname = returnvalue END FUNCTION funcname The unit knows NOTHING AT ALL about variables declared inside any other unit. It isn t aware that they exist and cannot use them. Therefore, the ONLY way to send information from the program unit to a function unit, or from one function unit to another, is by passing arguments from the calling unit to the called unit

9 Using a User-Defined Function: Example PROGRAM mean_function_test INTEGER,PARAMETER :: lower_bound = 1 INTEGER,PARAMETER :: memory_success = 0 REAL,DIMENSION(:),ALLOCATABLE :: input_value INTEGER :: number_of_elements, index INTEGER :: allocate_status, deallocate_status REAL :: input_mean REAL,EXTERNAL :: mean PRINT *, "How many elements are in the input_value" PRINT *, " (at least ", lower_bound, ")?" READ *, number_of_elements IF (number_of_elements < lower_bound) THEN PRINT *, "Idiot! I said at least ", lower_bound, ")!" END IF!! (number_of_elements < lower_bound) ALLOCATE(input_value(number_of_elements), STAT=allocate_status) IF (allocate_status /= memory_success) THEN PRINT *, "ERROR: can t allocate a REAL array ", "of ", number_of_elements, " elements." END IF!! (allocate_status /= memory_success) PRINT *, "What are the ", number_of_elements, " elements of the input_value?" READ *, (input_value(index), index = lower_bound, number_of_elements) input_mean = mean(input_value, number_of_elements) PRINT *, "The mean of the ", number_of_elements, " elements is ", input_mean, "." DEALLOCATE(input_value, STAT=deallocate_status) IF (deallocate_status /= memory_success) THEN PRINT *, "ERROR: can t deallocate a REAL array ", "of ", number_of_elements, " elements." END IF!! (deallocate_status /= memory_success) END PROGRAM mean_function_test Using a User-Defined Function: Example Run % f95 -o meanfunctestall meanfunctestall.f90 % meanfunctestall How many elements are in the input_value (at least 1 )? 6 What are the 6 elements of the input_value? The mean of the 6 elements is

10 Jargon: Program Unit Function Unit In a Fortran 90 program, the set of statements from the PROGRAM statement through the END PROGRAM statement is referred to as the program unit. Similarly, for a particular user-defined function, the set of statements from the FUNCTION statement through the END FUNCTION statement is referred to as that particular function unit. Another User-Defined Function Example Here s a definition of a user-defined function. REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root What can we say about this user-defined function? 1. Its name is cube root. 2. Its return type is REAL. 3. It has one argument, original value, whose type is REAL and whose intent is IN, so the argument already has a value when it is passed in, and the function will not change that value (that is, the function will treat the argument as if it were a named constant). 4. It has one local named constant, cube root power. 5. Its return variable is cube root. 6. It calculates and returns the cube root of the incoming argument. So, cube root calculates the cube root of a REAL argument and returns a REAL result whose value is the cube root of the argument. Does the name of a user-defined function have to be meaningful? Absolutely not; you could easily have a function named square root that always returns 12. But that d be REALLY REALLY DUMB, and you d get a VERY BAD GRADE

11 Using a User-Defined Function: Example #1 % cat cube_root_scalar.f90 PROGRAM cube_root_scalar INTEGER,PARAMETER :: number_of_values = 3 REAL :: input_value1, cube_root_value1 REAL :: input_value2, cube_root_value2 REAL :: input_value3, cube_root_value3 REAL,EXTERNAL :: cube_root! Function return type PRINT *, "What ", number_of_values, " real numbers would you like ", "the cube roots of?" READ *, input_value1, input_value2, input_value3 cube_root_value1 = cube_root(input_value1) cube_root_value2 = cube_root(input_value2) cube_root_value3 = cube_root(input_value3) PRINT *, "The cube root of ", input_value1, " is ", cube_root_value1, "." PRINT *, "The cube root of ", input_value2, " is ", cube_root_value2, "." PRINT *, "The cube root of ", input_value3, " is ", cube_root_value3, "." END PROGRAM cube_root_scalar The EXTERNAL Declaration PROGRAM cube_root_scalar REAL,EXTERNAL :: cube_root! Function return type END PROGRAM cube_root_scalar Notice this declaration: REAL,EXTERNAL :: cube root This declaration tells the compiler that there s a function named cube root with a return type of REAL, and that it s declared external to (outside of) the program unit that s calling the cube root function. REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root % f95 -o cube_root_scalar cube_root_scalar.f90 % cube_root_scalar What 3 real numbers would you like the cube roots of? 1, 8, 100 The cube root of is The cube root of is The cube root of E+02 is

12 Actual Arguments Formal Arguments PROGRAM cube_root_scalar cube_root_value1 = cube_root(input_value1) cube_root_value2 = cube_root(input_value2) cube_root_value3 = cube_root(input_value3) END PROGRAM cube_root_scalar REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value END FUNCTION cube_root When we talk about the arguments of a function, we re actually talking about two very different kinds of arguments. The arguments that appear in the call to the function for example, input value1, input value2 and input value3, in the program fragment above are referred to as actual arguments, because they re the values that are actually getting passed to the function. On the other hand, the arguments that appear in the definition of the function for example, original value, in the function fragment above are referred to as formal arguments, because they re the names that are used in the formal definition of the function. Jargon: in Fortran 90, you ll sometimes hear formal arguments referred to as dummy arguments. User-Defined Function Example #2: Array % cat cube_root_array.f90 PROGRAM cube_root_array INTEGER,PARAMETER :: first_input = 1 INTEGER,PARAMETER :: number_of_inputs = 5 REAL,DIMENSION(number_of_inputs) :: input_value, cube_root_value INTEGER :: index REAL,EXTERNAL :: cube_root PRINT *, "What ", number_of_inputs, " real numbers" PRINT *, " would you like the cube roots of?" READ *, (input_value(index), index = first_input, number_of_inputs) DO index = first_input, number_of_inputs cube_root_value(index) = cube_root(input_value(index)) END DO!! index = first_input, number_of_inputs DO index = first_input, number_of_inputs PRINT *, "The cube root of ", input_value(index), " is ", cube_root_value(index), "." END DO!! index = first_input, number_of_inputs END PROGRAM cube_root_array REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root % f95 -o cube_root_array cube_root_array.f90 % cube_root_array What 5 real numbers would you like the cube roots of? The cube root of is The cube root of is The cube root of E+02 is The cube root of E+02 is The cube root of E+02 is