001/* 002 * Java Genetic Algorithm Library (jenetics-6.1.0). 003 * Copyright (c) 2007-2020 Franz Wilhelmstötter 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 * 017 * Author: 018 * Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com) 019 */ 020package io.jenetics.prog.regression; 021 022import static java.util.Objects.requireNonNull; 023 024import io.jenetics.ext.util.Tree; 025 026import io.jenetics.prog.op.Op; 027 028/** 029 * This interface represents a set of sample points, which can be evaluated with 030 * a given evolved <em>program</em>. 031 * 032 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a> 033 * @version 6.0 034 * @since 6.0 035 */ 036@FunctionalInterface 037public interface Sampling<T> { 038 039 /** 040 * This class represents the result of a sample calculation, which contains 041 * the array of calculated values and a corresponding array with expected 042 * sample values. This two arrays can then be used for calculating the 043 * error between modeled regression function and actual sample values. 044 * 045 * @param <T> the sample result type 046 */ 047 final class Result<T> { 048 private final T[] _calculated; 049 private final T[] _expected; 050 051 private Result(final T[] calculated, final T[] expected) { 052 _calculated = requireNonNull(calculated); 053 _expected = requireNonNull(expected); 054 } 055 056 /** 057 * Return the the calculated result values. 058 * 059 * @return the the calculated result values 060 */ 061 public T[] calculated() { 062 return _calculated; 063 } 064 065 /** 066 * Return the expected sample result values. 067 * 068 * @return the expected sample result values 069 */ 070 public T[] expected() { 071 return _expected; 072 } 073 074 /** 075 * Create a new sampling result object. 076 * 077 * @param calculated the calculated values 078 * @param expected the expected sample values 079 * @param <T> the sample type 080 * @return a new sampling result object 081 * @throws NullPointerException if one of the arguments is {@code null} 082 */ 083 public static <T> Result<T> of(final T[] calculated, final T[] expected) { 084 return new Result<>(calculated.clone(), expected.clone()); 085 } 086 } 087 088 /** 089 * Evaluates the given {@code program} tree with its sample points. The 090 * returned result object may be {@code null} if no sample point has been 091 * added to the <em>sampling</em> when calling the {@code eval} method. 092 * 093 * @param program the program to evaluate 094 * @return the evaluated sample result. May be {@code null} if the sampling 095 * is empty and contains no sample points. 096 */ 097 Result<T> eval(final Tree<? extends Op<T>, ?> program); 098 099}