SELRand IEC Library for ACSELERATOR RTAC Projects

Transcription

1 SELRand IEC Library for ACSELERATOR RTAC Projects SEL Automation Controllers

2 Contents 1 Introduction 3 2 Supported Firmware Versions 4 3 Functions fun_rand (Function) fun_randrepeatable (Function) fun_randranged (Function) fun_randrangedrepeatable (Function) Appendices 7 Appendix A Release Notes 8 Appendix B Benchmarks 9 B.1 Benchmark Platforms B.2 Benchmark Test Descriptions B.2.1 fun_rand() B.2.2 fun_randranged() B.2.3 fun_randrepeatable() B.2.4 fun_randrangedrepeatable() B.3 Benchmark Results Appendix C Examples 11 C.1 Getting a Random Integer Between 10 and C.1.1 Objective C.1.2 Assumptions C.1.3 Solution C.2 Testing with Assorted Input C.2.1 Objective C.2.2 Assumptions C.2.3 Solution Schweitzer Engineering Laboratories, Inc. 2

3 1 Introduction The SELRand library contains a set of functions that return pseudo-random numbers for testing and other non cryptographic purposes. A pseudo-random number generator is a math function that takes advantage of its previous result and large number manipulations to perform operations that are not immediately predictable. The beginning value for each use of the sequence is called the seed. Generally, the seed is created from some measurement expected to have a wide range of variance. Commonly, this can be noise on a wire, small units of time, quantity and value of user input, or some other equally unpredictable quantity. Pseudo-random number generators do tend to be cyclic in nature, but they can have very large cycle times and excellent distribution. These functions are not intended to be used for implementing any security feature Schweitzer Engineering Laboratories, Inc. 3

4 2 Supported Firmware Versions This library can be used on any device that is configured using acselerator RTAC SEL-5033 Software with firmware version R132 or higher Schweitzer Engineering Laboratories, Inc. 4

5 3 Functions 3.1 fun_rand (Function) This function randomly seeds itself and returns a pseudo-random number in the range of 0 inclusive to 2 32 exclusive. Return IEC Type UDINT Description A random number between 0 inclusive to 2 32 exclusive. Processing At the first call of this function it randomly seeds itself. It will continually return pseudo-random values with each use. 3.2 fun_randrepeatable (Function) This function always seeds itself with the same value and returns a pseudo-random number in the range of 0 inclusive to 2 32 exclusive. Return IEC Type UDINT Description A random number between 0 inclusive to 2 32 exclusive. Processing At the first call of this function it seeds itself, always with the same value. It then returns the same sequence of pseudo-random values with each use. 3.3 fun_randranged (Function) This function randomly seeds itself and returns a pseudo-random number between minimum to maximum inclusive Schweitzer Engineering Laboratories, Inc. 5

6 Inputs Name IEC Type Description minimum UDINT The lower limit of the return value. maximum UDINT The upper limit of the return value. Return IEC Type UDINT Description A random number between minimum and maximum inclusive. Processing At the first call of this function, randomly seeds itself. It then continually returns pseudo-random values within the requested range. 3.4 fun_randrangedrepeatable (Function) This function always seeds itself with the same value and subsequently returns a pseudo-random number between minimum to maximum inclusive. Inputs Name IEC Type Description minimum UDINT The lower limit of the return value. maximum UDINT The upper limit of the return value. Return IEC Type UDINT Description A random number between minimum and maximum inclusive. Processing At the first call of function it seeds itself, always with the same value. It then continually returns the same sequence of pseudo-random values within the requested range Schweitzer Engineering Laboratories, Inc. 6

7 Appendices This page intentionally left blank Schweitzer Engineering Laboratories, Inc. 7

8 Appendix A Release Notes Version Summary Of Revisions Date Code Initial Release Schweitzer Engineering Laboratories, Inc. 8

9 Appendix B Benchmarks B.1 Benchmark Platforms The benchmarking tests recorded for this library are performed on the following platforms. SEL-3530 R134 firmware SEL-3354 Intel Pentium 1.4 GHz 1 GB DDR ECC SDRAM SEL-3532 RTAC Conversion Kit R132 firmware SEL-3555 Dual-core Intel i7-3555le processor 4 GB ECC RAM R134-V0 firmware B.2 Benchmark Test Descriptions All benchmark tests are based on an average of 100 calls to the function. B.2.1 fun_rand() The posted time is the average execution time of 100 consecutive calls. B.2.2 fun_randranged() The posted time is the average execution time of 100 consecutive calls with a range of 1 to 100. B.2.3 fun_randrepeatable() The posted time is the average execution time of 100 consecutive calls. B.2.4 fun_randrangedrepeatable() The posted time is the average execution time of 100 consecutive calls with a range of 1 to Schweitzer Engineering Laboratories, Inc. 9

10 B.3 Benchmark Results Operation Tested Time in µs per Platform SEL-3530 SEL-3354 SEL-3555 fun_rand() fun_randranged() fun_randrepeatable() fun_randrangedrepeatable() Schweitzer Engineering Laboratories, Inc. 10

11 Appendix C Examples These examples demonstrate the capabilities of this library. recommendations from SEL. They should not be mistaken as Users should implement the best practices of their organization when using these libraries. The user of these libraries is responsible for ensuring their correct implementation and verifying that the project using these libraries performs as expected. C.1 Getting a Random Integer Between 10 and 50 C.1.1 Objective A user knows the input for a function will vary between 10 and 50 and would like demonstrate the behavior of a function in a non-linear progression. C.1.2 Assumptions This example assumes that there is a user specified IEC function that is defined as shown in Code Snippet 1 FUNCTION fun_somefunction :REAL VAR_INPUT num : UDINT; END_VAR Code Snippet 1: fun_somefunction C.1.3 Solution The user can create the program in Code Snippet 2 to run the function 1000 times with assorted input Schweitzer Engineering Laboratories, Inc. 11

12 PROGRAM prg_randomwalk VAR i : UDINT; results : ARRAY [ ] OF REAL; randomnum : UDINT; END_VAR Code Snippet 2: prg_randomwalk FOR i := 1 to 1000 DO //This gives a random number from 10 to 50; randomnum := fun_randranged(10, 51); //Call the function with the random number results[i] := fun_somefunction(randomnum); END_FOR C.2 Testing with Assorted Input C.2.1 Objective A user wants to vary input for testing but would like to be able to recreate the inputs if something goes wrong. C.2.2 Assumptions This example assumes that there is a user-specified IEC function that is defined as shown in Code Snippet 3 FUNCTION fun_testfunction :BOOL VAR_INPUT num : UDINT; END_VAR Code Snippet 3: fun_testfunction C.2.3 Solution The user can create the program in Code Snippet 4 to run the function 1000 times with assorted input but a set order Schweitzer Engineering Laboratories, Inc. 12

13 PROGRAM prg_randomtest VAR i : UDINT; results : ARRAY [ ] OF REAL; randomnum : UDINT; END_VAR Code Snippet 4: prg_randomtest FOR i := 1 TO 1000 DO //This gives a random number; randomnum := fun_randrepeatable(); //Call the function with the random number results[i] := fun_testfunction(randomnum); END_FOR Schweitzer Engineering Laboratories, Inc. 13